SiYuan

// Overview

SiYuan is a privacy-first personal knowledge management system built around content blocks. Every block can be referenced and back-linked, carry custom attributes, be addressed by a `siyuan://` URL, and be pulled into a document by an embedded SQL query — which is what separates it from a folder of Markdown files. The editor is block-style Markdown WYSIWYG with list outlining, block zoom-in, math and diagram rendering, web clipping and PDF annotation links, and it is built to survive million-word documents.

Data lives on your own machine or your own server. It ships as desktop apps, Android, iOS and HarmonyOS apps, and a Docker image (`b3log/siyuan`) for self-hosting, where the `serve` subcommand takes a workspace path and an access code, with optional OIDC authentication against Google, Microsoft, GitHub or a custom provider. A built-in CLI reads and writes workspace data without a running server: notebooks, documents, blocks, attributes, tags, bookmarks, templates, full-text and SQL queries, backlinks, import/export, snapshots and sync — with `-f json` output for scripting and `--dry-run` on mutating commands.

The AI surface is deliberately modest: AI writing and question-answering through an OpenAI-compatible API, Tesseract OCR on assets, plus an HTTP API and a community marketplace of plugins, themes and templates that other tools (including MCP bridges) build on. Spaced-repetition flashcards, a table database view, JavaScript/CSS snippets and export to PDF, Word, HTML or standard Markdown round it out. The code is AGPL-3.0; most features are free, including for commercial use, while cloud sync and some extras are reserved for paid members.

// What it does

• Block-level references, two-way links, custom attributes and embedded SQL queries over your notes
• Markdown WYSIWYG editing with outlining, block zoom, formulas, diagrams, web clipping and PDF annotation
• Self-hosting via Docker with workspace mounting, access codes and optional OIDC login
• A scriptable CLI for notebooks, blocks, search, SQL, export/import, snapshots and sync — JSON output, `--dry-run`
• AI writing and Q&A chat through an OpenAI-compatible API, plus Tesseract OCR
• Spaced-repetition flashcards, database table views, plugin API and a community marketplace

// Getting started

Install the app from a store or package, or self-host the kernel with Docker. The CLI works against a workspace directory directly.

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

ln -s /Applications/SiYuan.app/Contents/Resources/kernel/SiYuan-Kernel /usr/local/bin/siyuan

siyuan notebook list -w ~/SiYuan
siyuan search "keyword" -w ~/SiYuan -f json
siyuan export md --id <block-id> -w ~/SiYuan

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Keep a personal or team knowledge base on hardware you control instead of a hosted notes SaaS
• Build structured notes where SQL queries over blocks assemble views instead of copy-pasting
• Feed an assistant your own notes through the CLI, HTTP API or a marketplace plugin
• Study with spaced repetition over the same blocks you write in

// How SiYuan compares

SiYuan alongside other open-source notes & knowledge bases tools AI/TLDR tracks, ranked by GitHub stars.