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

[SiYuan](https://b3log.org/siyuan/en_US/) 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.

![Unbreakable link in action: a code block edited in one document updates automatically in the document where it is embedded](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/1a391e35-e856-41d0-5eac-fbf39da0a600/md1x =1280x720)
## Self-hosting with Docker

### `docker-compose.yml`

```yaml
[label 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
```

![Clear view of the docker-compose.yml file in a code editor showing the configuration used to launch the SiYuan container](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/12ac5947-3501-4c0a-c031-afaf56d0ea00/orig =1280x720)


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

```command
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.

![A "Bug Tickets" database with Title, Status, and Priority columns showing how structured data is organized within a note](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/fac6cf99-8c7e-4a83-2e73-abf7f9b01000/lg2x =1280x720)

### 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.

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

![SQL query block showing a query run inside a note with structured results appearing below it](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/20f6f608-a090-469d-3ec0-246e3a286100/orig =1280x720)

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.

![Global graph view showing a complex network of interconnected notes](https://imagedelivery.net/xZXo0QFi-1_4Zimer-T0XQ/d0e40a27-7dce-4b32-ee22-ef9939463300/lg1x =1280x720)

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](https://github.com/siyuan-note/siyuan).