SiYuan: Block-Based Linking, Built-in Databases, and Self-Hosted Knowledge Management

SiYuan is an open-source, local-first personal knowledge management system that stores notes on your own machine. Its primary technical differentiator is block-based linking: every content element, paragraphs, headings, list items, code blocks, databases, receives a permanent unique ID. Links reference these IDs rather than file names, so restructuring and refactoring the knowledge base never breaks existing connections.

Block-based linking

In file-based note systems like Obsidian, links reference file names or paths. Renaming or moving a file breaks every incoming link. SiYuan eliminates this problem by making the block, not the file, the fundamental unit of information.

When you link to a code block or a paragraph, you link to its immutable ID. The block can move between documents, the document can be renamed, and the parent notebook can be reorganized, and every reference remains valid. This allows the same piece of content to be embedded in multiple locations without duplication. Editing the source block updates all embeddings.

Self-hosting with Docker

docker-compose.yml

version: "3.9"

services:
  siyuan:
    image: b3log/siyuan
    container_name: siyuan
    command: [ '--workspace=/siyuan/workspace', '--accessAuthCode=your_strong_password_here' ]
    ports:
      - "6806:6806"
    volumes:
      - ./siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=Asia/Dubai
      - PUID=1000
      - PGID=1000

Key configuration points:

• --accessAuthCode=your_strong_password_here sets the access password. Replace this before running.
• volumes: ./siyuan/workspace:/siyuan/workspace persists all notes to the host machine. Without this, data is lost when the container is removed.
• ports: "6806:6806" exposes the web interface.
• restart: unless-stopped restarts the container automatically after crashes or reboots.
• PUID and PGID control file ownership on the host volume.

Starting the container

docker-compose up -d

After the image downloads and the container starts, navigate to http://localhost:6806 and enter the access code configured above.

Key features

Databases

SiYuan includes native database blocks, similar to Notion's databases. Inserting a database block with /database creates a table with configurable column types: text, select, multi-select, date, number, and others. Databases are themselves blocks with permanent IDs, so they can be embedded and referenced like any other content.

SQL querying

SiYuan exposes its underlying SQLite database directly to users. Inserting a SQL block with /sql allows running standard SQL queries against note content. This is useful for creating dynamic views, filtering database entries by field values, or generating reports across multiple notebooks.

SELECT * FROM blocks 
WHERE path LIKE '%/Bug Tickets.sy' 
  AND type = 'i' 
  AND content LIKE '%High%' 
ORDER BY updated DESC 
LIMIT 3

The blocks table contains every block in the workspace. Queryable columns include id, content, type, path, created, and updated.

Graph view

The graph view visualizes every document and block as a node and every link as an edge. It supports a local mode showing connections for the current document and a global mode showing the entire workspace. Nodes are clickable and jump to the referenced content.

As the number of cross-document references grows, the graph view becomes useful for discovering non-obvious connections and understanding the overall structure of a knowledge base.

Comparison with Obsidian and Notion

SiYuan vs. Obsidian. Obsidian is file-based and stores content as plain Markdown. Links reference file names, so renaming or moving files breaks incoming links. SiYuan's block IDs solve this. Obsidian's database-like functionality (Dataview) is a community plugin; SiYuan's is built in. Obsidian's plugin ecosystem is larger and more mature, particularly for English-speaking users. SiYuan uses a proprietary .sy format rather than plain Markdown, which is a meaningful tradeoff for users who prioritize portability and plain text.

SiYuan vs. Notion. Notion is a cloud-based SaaS product. SiYuan is local-first and self-hosted. SiYuan's SQL querying has no direct Notion equivalent. Notion's primary advantage is real-time collaboration, which SiYuan does not support as a local-first tool.

Final thoughts

SiYuan's permanent block ID system is the most technically interesting aspect of the tool. It solves a real problem: the fragility of file-based link systems under reorganization. The combination of this with native databases and SQL querying makes it more suitable for complex, evolving knowledge bases than either Obsidian or Notion for users who do not need real-time collaboration.

The .sy format and smaller plugin ecosystem are the main reasons to pause before committing. For users whose primary requirement is plain-text portability or a large library of community extensions, Obsidian remains the stronger choice.

The source code and installation documentation are at github.com/siyuan-note/siyuan.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.