SiYuan: A Block-Based Knowledge Base That Keeps Your Data Local

What SiYuan Solves and Who It Serves

SiYuan targets individuals and small teams who want a personal knowledge management system without sending their notes to a cloud service. The README states it is a privacy-first system, and the Docker deployment option makes self-hosting straightforward. It is for people who need block-level references and two-way links, not just a flat Markdown file store. The editor is described as Markdown WYSIWYG, which appeals to users who want the simplicity of Markdown without losing visual formatting. The target audience includes researchers, writers, and developers who already manage their own infrastructure.

Block-Level References and the siyuan:// Protocol

The core mechanism is the content block. SiYuan treats each paragraph, heading, or list item as a block that can be referenced independently. The README lists block-level reference and two-way links as a key feature, along with custom attributes and SQL query embeds. This means you can link to a specific block, not just a page, and query your notes using SQL. The protocol siyuan:// is used to jump between blocks, which is how references resolve. This is a different approach from file-based tools like Obsidian, which link to whole files unless you use plugins. The block model also supports block zoom-in, letting you focus on a single block and its children.

Getting Started: Installation and Configuration

The README recommends installing through app markets for one-click updates, but the Docker route is the most relevant for server deployment. The image is b3log/siyuan, and the program lives under /opt/siyuan/ inside the container. The file structure is described as the resource directory, but the README is truncated. For a local install, you can download packages from B3log or GitHub releases. The command-line interface is mentioned, but no specific commands are shown in the README. You will need to check the online user guide for exact Docker run commands, because the README does not provide them.

Data Storage and Sync: What the FAQ Reveals

The FAQ covers data storage and third-party sync. It asks how SiYuan stores data and whether it supports synchronization through a third-party sync disk. The answers are not in the provided text, but the existence of these questions tells you that data portability is a concern for users. The data repo key is mentioned in another FAQ question, which implies that SiYuan encrypts or signs its data repository. Losing that key is a serious issue, so you must back it up. This is a real operational constraint. If you plan to sync via Dropbox or Syncthing, you need to verify whether SiYuan's data format is safe to sync while the app is running.

The Paid Feature Split: A Real Limitation

The README says most features are free, even for commercial use, but some features are only available to paid members. It points to a pricing page for details. This is a genuine limitation: the feature set is not fully open. The AI writing and Q/A chat via OpenAI API is listed under features, but it may be one of the paid ones. The table view, flashcard spaced repetition, and Tesseract OCR are also listed, but you cannot tell from the README which ones require a subscription. For an open source project, this hybrid model can be confusing. You must check the pricing page before relying on any specific feature.

Architecture and Ecosystem: More Than a Single Repo

SiYuan is not a single project. The README lists several companion repositories: lute for the editor engine, dejavu for the data repo, petal for the plugin API, and riff for spaced repetition. There are also mobile apps for Android, iOS, and HarmonyOS, plus a Chrome extension. This modular architecture means you can contribute to or fork individual components. The plugin API (petal) suggests extensibility, and the community marketplace (bazaar) allows sharing plugins and themes. However, this also means the project has a larger maintenance surface. If you adopt SiYuan, you are depending on multiple repositories, not just one.

Licensing and Upgrade Considerations

SiYuan is licensed under AGPL-3.0. This is a strong copyleft license. If you modify the source and offer it as a network service, you must release your modifications under the same license. For personal use, this is usually not a problem, but for organizations, it can be a legal concern. The README claims most features are free for commercial use, but that refers to the software itself, not your obligations under AGPL. Upgrades are handled through app markets or by pulling new Docker images. The release history shows frequent beta releases, which indicates active development. You should expect to follow the changelog to understand breaking changes.

Alternatives: How SiYuan Differs from File-Based Tools

The most direct alternative is Obsidian, which also supports backlinks and is popular for knowledge management. The key difference is the data model. Obsidian stores notes as plain Markdown files in a folder, making it easy to sync and edit with any tool. SiYuan uses a block-based model with its own data repository, which enables SQL queries and block-level references but makes the data less transparent. Another alternative is Logseq, which is also block-based and open source. Logseq stores data as Markdown files with block properties, so it is more portable than SiYuan. If you need fine-grained references and are willing to accept a proprietary data format, SiYuan is a strong choice. If you want plain files, choose Obsidian or Logseq.

Editorial conclusion

Adopt SiYuan if you need a self-hosted, block-based knowledge base with fine-grained references and are comfortable with AGPL-3.0. Avoid it if you require all features without a subscription or if your organization prohibits copyleft licenses. Before adopting, verify the current pricing page to see which features are paid, test the data repo key backup process, and confirm that the Docker image meets your deployment needs.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes