Stop Losing Your Notes to Big Tech! Use SiYuan Instead

Your thoughts are being harvested. Every note you scribble in Notion, every document you draft in Google Docs, every wiki page you build in Confluence—they all live on someone else's servers. Your intellectual property, your creative process, your second brain: rented, not owned. And when the pricing changes, the API breaks, or the service shuts down? Poof. Your knowledge disappears like it never mattered.

But what if you could truly own your ideas? What if your personal knowledge management system lived exactly where you wanted it—on your laptop, your home server, or a private cloud you control? Enter SiYuan, the open-source knowledge base that's making developers, researchers, and power users abandon proprietary note-taking apps in droves. Built with TypeScript and Go, SiYuan delivers something the Silicon Valley giants never will: complete privacy, block-level precision, and the freedom to refactor your thinking without a subscription ransom.

This isn't just another Markdown editor. This is a block-level knowledge revolution—and you're about to see why thousands of developers are starring this repository every month.

What is SiYuan?

SiYuan (思源, meaning "source of thought") is a privacy-first, self-hosted, fully open-source personal knowledge management system that reimagines how we capture, connect, and cultivate ideas. Born from the B3log open-source community and actively maintained on GitHub, SiYuan represents a radical departure from the SaaS-first mentality that has dominated productivity software for the past decade.

The project is architected as a sophisticated dual-layer system: a Go-powered kernel handles data persistence, synchronization, and API services, while a TypeScript/React frontend delivers a buttery-smooth editing experience. This separation isn't academic—it enables everything from desktop apps to Docker deployments to mobile experiences on Android, iOS, and even HarmonyOS, all speaking the same block-level language.

What makes SiYuan genuinely trending now? Three converging forces. First, privacy paranoia has gone mainstream—developers who once laughed at self-hosting are now running their own infrastructure. Second, the block-based editing paradigm pioneered by tools like Roam Research and Notion has proven its superiority for connected thinking, but users are tired of vendor lock-in. Third, SiYuan's AGPLv3 licensing guarantees these freedoms forever: no bait-and-switch open-core model, no surprise acquisition that kills the project.

The repository itself tells a compelling growth story. With thousands of GitHub stars accumulating steadily, active CI/CD pipelines, and a flourishing ecosystem of satellite projects—editor engines, browser extensions, community marketplaces, and dedicated mobile apps—SiYuan has transcended "promising experiment" to become a legitimate Notion and Obsidian competitor with a fundamentally different value proposition: your data, your rules, your infrastructure.

Key Features That Separate SiYuan from the Pack

SiYuan's feature set reads like a wishlist from developers who've been burned by proprietary tools one too many times. Here's what makes it technically exceptional:

Block-Level Reference Architecture Unlike document-based systems where links break when you reorganize, SiYuan treats every paragraph, heading, list item, and code block as a first-class entity with a unique ID. This enables bidirectional linking that survives any restructuring. Reference a specific theorem from your math notes in your project documentation, and the connection persists even if you move, rename, or nest the original block ten levels deep.

Native Markdown WYSIWYG SiYuan doesn't force you to choose between raw Markdown editing and rich visual formatting. Its block-style editor renders formatting in real-time while preserving clean Markdown underneath. Mathematical formulas via KaTeX, Mermaid diagrams, flowcharts, Gantt charts, timing diagrams, and even musical staffs—all render natively without plugin dependency hell.

SQL Query Embedding Here's where power users get goosebumps. SiYuan exposes its block structure through SQL queries embedded directly in documents. Want a dynamic table of all blocks tagged #urgent across your entire knowledge base? Write the SQL, embed it, and watch it update automatically. This transforms static documents into living dashboards.

Multi-Platform Deployment Desktop (Windows/Mac/Linux) via Electron, mobile apps for three operating systems, or Docker containerization for server deployment—the same codebase adapts to your infrastructure needs. The siyuan:// protocol enables deep linking from any application on your system.

Extensibility Ecosystem JavaScript/CSS snippets for UI customization, a plugin API via the Petal project, template snippets for rapid document creation, and a community marketplace for sharing extensions. The browser extension enables web clipping with intelligent content extraction.

AI Integration (OpenAI API) Native AI writing assistance and Q/A chat functionality, but critically—you bring your own API key. No hidden AI training on your data, no opaque "smart features" that phone home to mystery endpoints.

Data Sovereignty Features Local-first storage in transparent JSON format, optional end-to-end encrypted synchronization via member services, and complete export portability to standard Markdown with assets, PDF, Word, and HTML formats.

Real-World Use Cases Where SiYuan Dominates

1. The Researcher's Living Lab Notebook

Academic researchers juggle hundreds of papers, experiments, and half-formed hypotheses. SiYuan's block-level references let you quote specific claims from papers, connect them to your experimental notes, and trace idea lineages backward and forward. The flashcard spaced repetition system (via the Riff project) turns literature reviews into retention engines. SQL queries can surface "all claims about protein folding from 2023 papers rated highly."

2. The Developer's Technical Wiki

Engineering teams need documentation that evolves with code. SiYuan's siyuan:// protocol links from your IDE, terminal, or CI/CD dashboards directly to relevant documentation blocks. The API surface enables programmatic document generation from code comments. Custom attributes on blocks let you tag documentation with version compatibility, deprecation status, or ownership—then query dynamically.

3. The Writer's Nonlinear Composition Studio

Long-form writers using tools like Scrivener face export nightmares. SiYuan's million-word large document editing handles novel-scale projects, while block zoom-in lets you focus on individual scenes without losing narrative context. Export to WeChat MP, Zhihu, and Yuque formats means native publishing without Markdown-to-HTML conversion grief.

4. The Privacy-Paranoid Consultant's Client Vault

Consultants handling sensitive client data can't risk proprietary cloud leaks. Self-hosted Docker deployment with custom accessAuthCode protection keeps intellectual property on infrastructure you audit. The Tesseract OCR integration digitizes handwritten meeting notes without sending images to Google Vision or AWS Textract.

5. The Remote Team's Async Knowledge Base

Distributed teams using Notion wake up to pricing surprises. SiYuan's Docker deployment on a $5 VPS gives equivalent collaborative functionality (via web access) with predictable infrastructure costs and the ability to air-gap sensitive projects entirely.

Step-by-Step Installation & Setup Guide

SiYuan meets you where you are—whether that's a double-click installer or a Kubernetes manifest. Here's how to deploy for maximum control.

Desktop Quick Start

For immediate exploration, grab the latest release:

# macOS (Homebrew)
brew install --cask siyuan

# Windows (Winget)
winget install B3log.SiYuan

# Linux (AppImage or package from GitHub)
wget https://github.com/siyuan-note/siyuan/releases/download/v3.0.0/siyuan-3.0.0-linux.AppImage
chmod +x siyuan-3.0.0-linux.AppImage
./siyuan-3.0.0-linux.AppImage

Or use the application markets: Microsoft Store, App Store, Google Play, or F-Droid for automatic updates.

Docker Deployment (Recommended for Power Users)

The Docker approach gives you server-grade persistence and access from any browser:

# Create workspace directory with proper ownership
mkdir -p /siyuan/workspace
chown -R 1000:1000 /siyuan/workspace

# Run with explicit security parameters
docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=America/New_York \
  b3log/siyuan \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=YOUR_STRONG_AUTH_CODE_HERE

Critical parameters explained:

• --workspace: Mounts your persistent data directory
• --accessAuthCode: Mandatory access control—never expose port 6806 without this
• PUID/PGID: Ensures file ownership matches your host user, preventing permission conflicts

Docker Compose (Production-Ready)

For sustainable deployments, use this docker-compose.yml:

version: "3.9"
services:
  siyuan:
    image: b3log/siyuan
    command: ['--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode}']
    ports:
      - "6806:6806"
    volumes:
      - /siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=America/New_York
      - PUID=1000
      - PGID=1000

Deploy with:

# Create .env file with your credentials
echo "AuthCode=$(openssl rand -base64 32)" > .env

# Start services
docker-compose up -d

# Verify logs
docker-compose logs -f siyuan

Reverse Proxy Configuration

For HTTPS and custom domains, configure NGINX:

server {
    listen 443 ssl http2;
    server_name notes.yourdomain.com;

    location / {
        proxy_pass http://localhost:6806;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    # Critical: WebSocket support for real-time collaboration
    location /ws {
        proxy_pass http://localhost:6806/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

REAL Code Examples from the Repository

Let's examine actual deployment patterns and configuration from SiYuan's documentation, with detailed technical commentary.

Example 1: Production Docker Deployment with Custom User Permissions

The README provides this sophisticated Docker run command that solves real permission headaches:

docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  b3log/siyuan \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=xxx

Technical breakdown:

• -d detaches the container for background operation
• -v creates a bind mount: host path /siyuan/workspace maps to identical container path
• -p 6806:6806 exposes SiYuan's default kernel port
• -e PUID=1001 -e PGID=1002 passes custom user/group IDs to the entrypoint script
• --workspace=/siyuan/workspace/ tells SiYuan where data lives (must match volume mount)
• --accessAuthCode=xxx sets the authentication barrier

The entrypoint.sh script dynamically creates a siyuan user with these IDs, solving the classic Docker volume permission mismatch where container processes can't write to host directories. This eliminates the need for chmod 777 security disasters.

Example 2: Docker Compose with Environment Variable Substitution

For teams managing multiple environments, this pattern from the README enables clean secret handling:

version: "3.9"
services:
  main:
    image: b3log/siyuan
    command: ['--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode}']
    ports:
      - 6806:6806
    volumes:
      - /siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=${YOUR_TIME_ZONE}
      - PUID=${YOUR_USER_PUID}
      - PGID=${YOUR_USER_PGID}

Implementation notes:

• ${AuthCode} pulls from shell environment or .env file—never commit credentials to version control
• ${YOUR_TIME_ZONE} ensures consistent timestamp behavior across deployments
• restart: unless-stopped provides resilience against host reboots or container crashes
• The command array overrides default entrypoint parameters while preserving the entrypoint.sh user creation logic

Deploy with explicit variable injection:

export AuthCode=$(openssl rand -hex 16)
export YOUR_TIME_ZONE=Europe/Berlin
export YOUR_USER_PUID=$(id -u)
export YOUR_USER_PGID=$(id -g)
docker-compose up -d

Example 3: TrueNAS Scale Deployment with ZFS Dataset

For homelab enthusiasts, the README includes this precise ZFS and Docker Compose integration:

# Create dedicated dataset for application data
zfs create Pool_1/Apps_Data/siyuan

# Set ownership matching container's expected PUID/PGID
chown -R 1001:1002 /mnt/Pool_1/Apps_Data/siyuan
chmod 755 /mnt/Pool_1/Apps_Data/siyuan

Then install via TrueNAS's custom YAML:

services:
  siyuan:
    image: b3log/siyuan
    container_name: siyuan
    command: ['--workspace=/siyuan/workspace/', '--accessAuthCode=2222']
    ports:
      - 6806:6806
    volumes:
      - /mnt/Pool_1/Apps_Data/siyuan:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=America/Los_Angeles
      - PUID=1001
      - PGID=1002

Why this matters: ZFS datasets provide snapshotting, compression, and integrity checking that generic Docker volumes lack. The explicit 1001:1002 ownership prevents the permission cascade failures common in NAS environments where default root ownership breaks application functionality.

Example 4: Unraid Template Configuration

For the popular Unraid NAS platform:

Web UI: 6806
Container Port: 6806
Container Path: /home/siyuan
Host path: /mnt/user/appdata/siyuan
PUID: 1000
PGID: 1000
Publish parameters: --accessAuthCode=******

Pre-creation ownership fix:

chown -R 1000:1000 /mnt/user/appdata/siyuan

Unraid-specific insight: The /mnt/user/appdata/ path is Unraid's standard for application data that survives array operations. The pre-emptive chown prevents the common failure mode where Docker creates directories as root before the entrypoint script executes.

Advanced Usage & Best Practices

Data Repo Key Management Your data repo key encrypts synchronization data. The README warns: initialize on one device, then import to others—never let devices generate independent keys. If lost, follow the documented reset procedure: backup via Export Data, reset the repo, reinitialize, and abandon old cloud snapshots.

Workspace Structure Mastery Understand your data layout:

• assets/: All inserted images, files, PDFs
• snippets/: Custom CSS/JS for UI modification
• templates/: Reusable document templates
• plugins/: Community and custom extensions
• *.sy files: JSON-encoded block structures

Performance Optimization For million-word documents, leverage block zoom-in rather than loading entire outlines. Use SQL embeds with LIMIT clauses for large result sets. Enable automatic update downloads in Settings > About to stay current with kernel optimizations.

Security Hardening

• Never expose port 6806 directly to the internet without accessAuthCode
• Use SIYUAN_ACCESS_AUTH_CODE_BYPASS=true only in air-gapped development environments
• Configure NGINX with WebSocket proxying—URL rewriting breaks authentication
• Verify volume mounts before container deletion; data loss is permanent

Comparison with Alternatives

SiYuan wins when: You need server deployment, want SQL-powered dynamic documents, require cross-platform mobile support including HarmonyOS, or demand AGPLv3 guarantees against proprietary capture.

FAQ: What Developers Ask About SiYuan

Q: Does SiYuan support syncing through Dropbox, Google Drive, or Syncthing? A: No—and deliberately so. Third-party sync disks risk data corruption due to SiYuan's database-like workspace structure. Use the built-in synchronization (member feature) or manual export/import workflows. The integrity of block-level references depends on atomic operations that file sync can't guarantee.

Q: Is SiYuan actually fully open source, or open-core? A: Fully open source under AGPLv3. The kernel, UI, Android app, iOS app, HarmonyOS app, and browser extension are all publicly available. Member features are convenience layers (cloud sync, AI quotas), not core functionality gates.

Q: How do I migrate from Notion or Obsidian? A: Export to standard Markdown from your current tool, then use SiYuan's import function. Block references will need manual reconstruction—this is the cost of escaping proprietary formats. The assets folder structure preserves your media.

Q: Can I use SiYuan offline completely? A: Absolutely. Desktop and mobile apps function entirely offline. Docker deployments on your LAN need no internet. AI features require OpenAI API connectivity, but all core editing, linking, and querying work air-gapped.

Q: What's the upgrade path for Docker deployments? A: Pull the new image, recreate the container with the same volume mount. Your workspace data persists independently. The restart: unless-stopped policy in Docker Compose handles this automatically with docker-compose pull && docker-compose up -d.

Q: Why does my block icon disappear in nested lists? A: First sub-blocks under list items intentionally hide icons for visual cleanliness. Press Ctrl+/ with cursor in the block to access the block menu directly.

Q: Is there commercial licensing for enterprise use? A: Most features are free even for commercial use. Member privileges enhance convenience but don't restrict deployment scale. Review the pricing page for specific feature tiers.

Conclusion: Own Your Thinking, Starting Now

SiYuan isn't merely a Notion alternative or an Obsidian competitor—it's a fundamental reassertion of intellectual sovereignty. In an era where your notes train someone else's AI and your workflows hostage to pricing committees, SiYuan delivers something radical: technology that serves you exclusively, licensed to stay that way forever.

The block-level architecture transforms how you connect ideas. The SQL embedding turns documents into applications. The Docker deployment puts enterprise-grade knowledge management on a $5 VPS. And the AGPLv3 license means this freedom compounds as the community grows.

I've watched too many developers build their second brains in walled gardens, only to face export nightmares when terms change. SiYuan is the escape hatch—mature enough for production, open enough for trust, and architecturally sophisticated enough for the most demanding knowledge workflows.

Your move. Star the repository, spin up the Docker container, and experience what it feels like when your notes truly belong to you. The source of thought awaits at github.com/siyuan-note/siyuan.