# SiYuan User Guide

SiYuan is a privacy-first, local-first personal knowledge management (PKM) system built around **content blocks**. Every paragraph, heading, list item, code block, and table you write is an addressable block that you can reference, embed, query, and rearrange. It combines a Markdown WYSIWYG editor with block-level bidirectional links, a built-in database, spaced-repetition flashcards, and a community marketplace — and it keeps all of your data in plain files on your own device.

This guide is written for people who **use** SiYuan: how to install it, write in it, organize knowledge, and get the most out of its features. For architecture, the HTTP API, configuration internals, deployment, and security hardening, see the companion **Admin Guide**.

> [!NOTE]
> SiYuan runs the same way everywhere: a local **kernel** (the engine that stores and indexes your data) plus a **UI** (desktop window, mobile app, or browser tab). You normally never see the kernel — you just open the app and start writing.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Installation](#2-installation)
3. [Core Concepts](#3-core-concepts)
4. [The Workspace and Your Data](#4-the-workspace-and-your-data)
5. [Writing in the Editor](#5-writing-in-the-editor)
6. [Blocks, References, and Links](#6-blocks-references-and-links)
7. [Organizing: Notebooks, Documents, and Daily Notes](#7-organizing-notebooks-documents-and-daily-notes)
8. [Databases (Attribute Views)](#8-databases-attribute-views)
9. [Search and Find/Replace](#9-search-and-findreplace)
10. [Flashcards and Spaced Repetition](#10-flashcards-and-spaced-repetition)
11. [Templates and Snippets](#11-templates-and-snippets)
12. [The Marketplace (Bazaar)](#12-the-marketplace-bazaar)
13. [Import and Export](#13-import-and-export)
14. [Web Clipping](#14-web-clipping)
15. [AI Assistant](#15-ai-assistant)
16. [Synchronization and Backup](#16-synchronization-and-backup)
17. [Appearance and Customization](#17-appearance-and-customization)
18. [Common Workflows](#18-common-workflows)
19. [How SiYuan Works (Concepts)](#19-how-siyuan-works-concepts)
20. [Troubleshooting](#20-troubleshooting)
21. [FAQ](#21-faq)
22. [Reference](#22-reference)

---

## 1. Quick Start

This section gets you from zero to your first linked note in a few minutes.

### 1.1 Install and open

=== "Desktop (Windows / macOS / Linux)"

    1. Download the installer for your platform from the [official site](https://b3log.org/siyuan/en/download.html) or [GitHub Releases](https://github.com/siyuan-note/siyuan/releases).
    2. Run the installer and launch **SiYuan**.
    3. On first launch SiYuan creates a default workspace at `~/SiYuan/` (your home folder).

=== "Mobile (Android / iOS / HarmonyOS)"

    1. Install from the [App Store](https://apps.apple.com/us/app/siyuan/id1583226508), [Google Play](https://play.google.com/store/apps/details?id=org.b3log.siyuan), or [F-Droid](https://f-droid.org/packages/org.b3log.siyuan).
    2. Open the app; it creates a workspace inside the app's data directory.

=== "Self-hosted (Docker, browser access)"

    ```bash
    docker run -d \
      -v /siyuan/workspace:/siyuan/workspace \
      -p 6806:6806 \
      -e PUID=1000 -e PGID=1000 \
      b3log/siyuan \
      --workspace=/siyuan/workspace/ \
      --accessAuthCode=please-change-me
    ```

    Then open `http://localhost:6806` in a browser. See the Admin Guide for full self-hosting details.

### 1.2 Write your first document

1. In the left **doc tree**, you start with one notebook open. Click the **+** next to it to create a new document and give it a title.
2. Start typing. Press <kbd>Enter</kbd> to create a new block. Each line you write is its own block.
3. Use Markdown shortcuts as you type — `# ` for a heading, `- ` for a bullet, `> ` for a quote, ` ``` ` for a code block. SiYuan converts them live (WYSIWYG).

### 1.3 Create your first block reference

1. Type `(( ` anywhere in a block. A search popup appears.
2. Type a few words that match another block, pick it, and press <kbd>Enter</kbd>. SiYuan inserts a **block reference** — a live link to that exact block.
3. Open the referenced block and look at its **backlink** panel: your new reference shows up there automatically. You now have a two-way link.

> [!TIP]
> The fastest way to learn SiYuan is to open the built-in **user guide notebook** (created automatically in a fresh workspace). It is itself a SiYuan document, so you can click around, edit it, and see features in action.

---

## 2. Installation

SiYuan ships as a native app on every major platform, plus a server image for self-hosting. Pick the channel that matches how you want to use it.

### 2.1 Desktop installation

| Channel | Where | Notes |
|---|---|---|
| Installer package | [B3log download](https://b3log.org/siyuan/en/download.html), [GitHub Releases](https://github.com/siyuan-note/siyuan/releases) | Standard install, supports built-in auto-update |
| Microsoft Store | [Store listing](https://apps.microsoft.com/detail/9p7hpmxp73k4) | One-click updates via the Store |
| Package managers | See [Repology `siyuan`](https://repology.org/project/siyuan/versions) / [`siyuan-note`](https://repology.org/project/siyuan-note/versions) | Community-maintained packages for many Linux distros |

> [!TIP]
> Installing through an app market (Microsoft Store, app stores) lets you upgrade with one click later. If you use a downloaded installer, enable **Settings → About → Automatically download update installation package** so SiYuan keeps itself current.

### 2.2 Mobile installation

| Platform | Store |
|---|---|
| iOS / iPadOS | [App Store](https://apps.apple.com/us/app/siyuan/id1583226508) |
| Android | [Google Play](https://play.google.com/store/apps/details?id=org.b3log.siyuan), [F-Droid](https://f-droid.org/packages/org.b3log.siyuan) |
| HarmonyOS | Native HarmonyOS app (see the [siyuan-harmony](https://github.com/siyuan-note/siyuan-harmony) project) |

### 2.3 Self-hosted server (Docker)

The Docker image `b3log/siyuan` runs the kernel headless and serves the UI to any browser on port `6806`. This is ideal for accessing your notes from multiple devices over your own network.

```bash
docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1000 -e PGID=1000 \
  b3log/siyuan \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode=please-change-me
```

> [!CAUTION]
> Always set `--accessAuthCode` (or the `SIYUAN_ACCESS_AUTH_CODE` environment variable) to a strong value when self-hosting. Without it, anyone who can reach port `6806` can read and edit your data. The Admin Guide covers the full security model.

> [!WARNING]
> The Docker/browser deployment has deliberate limitations: it does **not** accept desktop or mobile app connections (browser only), it does **not** support exporting to PDF/HTML/Word, and it does **not** support importing Markdown files. For those features, use the desktop app.

### 2.4 Insider preview

Major updates are released first as **Insider** builds. If you want to test upcoming features early, see [siyuan-note/insider](https://github.com/siyuan-note/insider).

---

## 3. Core Concepts

A few ideas make everything else in SiYuan click. Read this section once and the rest of the app will feel natural.

**Content block**
: The atomic unit of SiYuan. A paragraph, heading, list, list item, code block, table, quote, math block, or embedded database is each a *block*. Every block has a unique ID and can be referenced, embedded, moved, folded, and given attributes independently.

**Document**
: A tree of blocks stored as a single `.sy` file (JSON format). A document is itself a block (the document block), so you can reference a whole document just like any paragraph inside it.

**Notebook**
: A top-level container of documents — think of it as a project or a major area of your knowledge base. You can open and close notebooks independently. Each notebook is a folder on disk.

**Block reference**
: A live pointer from one block to another, written with `((...))`. The target block keeps a **backlink** to every block that references it, giving you automatic bidirectional links.

**Attribute**
: Arbitrary key/value metadata you can attach to any block (name, alias, memo, bookmark, custom fields). Attributes power naming, the database, and advanced queries.

**Workspace**
: The single folder that holds everything — your notebooks, assets, settings, and history. You can have several workspaces and switch between them.

> [!IMPORTANT]
> Because everything is a block with a stable ID, links never break when you move content around. You can drag a paragraph to a different document and every reference to it keeps working.

---

## 4. The Workspace and Your Data

SiYuan stores **all** of your data inside a single workspace folder on your device. Knowing its layout helps you back up confidently and understand exactly where your notes live.

### 4.1 Workspace location

| Platform | Default workspace |
|---|---|
| Desktop | `~/SiYuan/` (your home directory) |
| Docker | the path you pass to `--workspace` |
| Mobile | inside the app's private storage |

You can move or create additional workspaces from **Settings** or the workspace switcher.

### 4.2 What lives in the workspace

Inside the workspace, the `data/` folder holds your knowledge base:

| Folder | Contents |
|---|---|
| `data/<notebook>/` | One folder per notebook; documents are `.sy` JSON files inside |
| `data/assets/` | All inserted files: images, PDFs, audio, video, attachments |
| `data/emojis/` | Custom emoji images |
| `data/snippets/` | Code snippets (JavaScript/CSS) |
| `data/storage/` | Saved search criteria, layouts, flashcard state |
| `data/templates/` | Template snippets |
| `data/widgets/` | Widgets |
| `data/plugins/` | Installed plugins |
| `data/public/` | Files served publicly via the kernel |

Alongside `data/` you'll find `conf/` (settings), `history/` (file history snapshots), `repo/` (the encrypted data repo used for sync and snapshots), and `temp/` (caches and logs, including `temp/siyuan.log`).

> [!NOTE]
> A document file uses the `.sy` extension and stores its block tree as JSON. The rest of the folders under `data/` are exactly as listed above — there is no hidden database holding your content; your notes are real files you can copy.

### 4.3 Backing up your data

Because your data is just files, the simplest backup is to copy the whole workspace folder (or at least `data/`) somewhere safe. SiYuan also offers structured backup options:

- **Settings → Export → Export Data** writes a portable archive of your entire data folder.
- The **data repo** keeps versioned snapshots you can roll back to (see [Synchronization and Backup](#16-synchronization-and-backup)).

> [!CAUTION]
> Do **not** put your workspace inside a third-party file-sync folder (Dropbox, OneDrive, Google Drive, iCloud Drive, Syncthing, etc.). Those tools sync files individually and can corrupt SiYuan's data while it is writing. Use SiYuan's own sync instead. See the [FAQ](#21-faq).

---

## 5. Writing in the Editor

SiYuan's editor is a **block-style Markdown WYSIWYG** editor (its codename is *Protyle*). You type Markdown and it renders instantly — there is no separate "preview" mode.

### 5.1 Markdown shortcuts

Type these at the start of a block and SiYuan converts the block as you type:

| You type | You get |
|---|---|
| `# ` … `###### ` | Heading levels 1–6 |
| `- ` or `* ` | Bulleted list |
| `1. ` | Numbered list |
| `- [ ] ` | Task list item |
| `> ` | Quote (blockquote) |
| ` ``` ` | Code block (then type the language) |
| `$$` | Math block (LaTeX) |
| `--- ` | Horizontal divider |
| `| a | b |` | Table |

Inline formatting works the usual Markdown way: `**bold**`, `*italic*`, `~~strikethrough~~`, `` `code` ``, `==highlight==`, `$inline math$`.

### 5.2 The block menu and the gutter

Hover over the left edge of any block to reveal the **gutter** icon. Click it (or press <kbd>Ctrl</kbd>+<kbd>/</kbd> with the cursor in the block) to open the **block menu**, where you can:

- Convert the block to another type
- Add it to flashcards, bookmarks, or set attributes
- Copy its block reference, embed, or a protocol link
- Move, fold, or delete it

> [!TIP]
> If a block (such as the first paragraph inside a list item) seems to have no gutter icon, move the cursor into it and press <kbd>Ctrl</kbd>+<kbd>/</kbd> to open its block menu anyway. This is expected behavior, not a bug.

### 5.3 Rich content blocks

SiYuan renders a wide range of embedded content directly in the editor:

- **Math** — LaTeX formulas, inline and block, via KaTeX.
- **Diagrams** — Mermaid flowcharts, sequence/Gantt/state diagrams; PlantUML; Graphviz; flowchart.js; ABC music notation; ECharts; mind maps.
- **Code** — syntax-highlighted code blocks with optional line numbers, line wrap, and ligatures.
- **Media** — images, audio, and video blocks; embedded web pages (IFrame blocks).
- **Super blocks** — group several blocks side by side or stacked as a single unit.
- **Callouts and quotes** — visually distinct note boxes.

### 5.4 Editing large documents

SiYuan supports **million-word documents** by dynamically loading blocks as you scroll, so even very large notes stay responsive. You can **zoom in** to any block to focus on it and its children as if it were its own document, then zoom back out.

### 5.5 Tabs, panels, and windows

- **Multi-tab**: open many documents as tabs in a panel.
- **Split screen**: drag a tab to the edge of the window to split horizontally or vertically.
- **Multi-window** (desktop): pop a document out into its own window.
- **Multi-workspace**: run separate workspaces in separate windows.

---

## 6. Blocks, References, and Links

This is the heart of SiYuan: weaving your notes into a connected graph.

### 6.1 Block references

A **block reference** is a live link to a specific block. Create one by typing `(( ` and searching for the target, or by copying a block's reference from its block menu and pasting it.

- The reference shows the target's **anchor text** (by default the block's content or name). You can override the anchor text per reference.
- Click a reference to jump to the target. Hover to preview it in a floating window.

### 6.2 Backlinks and mentions

Open any block's **Backlinks** panel to see:

- **Backlinks** — every block that explicitly references this one.
- **Mentions** — blocks that mention this block's name/alias as plain text without an explicit link (useful for discovering connections you can promote into real references).

You can control how many backlinks expand by default and how mentions are matched (by name, alias, anchor, or document) in **Settings → Search**.

### 6.3 Virtual references

**Virtual references** automatically highlight any text that matches the name or alias of an existing block, turning your whole knowledge base into an implicit web of links without you typing `((`. Enable and tune them in **Settings → Editor** (you can set include/exclude keyword lists).

### 6.4 Embedding blocks

An **embed** displays the live content of another block (or the result of a query) inline. Type `{{ ` to create an embed. Unlike a reference (which is a small link), an embed shows the full content and updates when the source changes. You can use a SQL query to embed many blocks at once (see below).

### 6.5 SQL query embeds

SiYuan indexes every block in a SQLite database, and you can query it directly. An embed block can contain a SQL `SELECT` against the block index to pull in exactly the blocks you want — for example, all blocks with a given tag, all task items due today, or all children of a document.

```sql
SELECT * FROM blocks WHERE content LIKE '%project alpha%' AND type = 'p' ORDER BY updated DESC LIMIT 20
```

> [!TIP]
> SQL query embeds are the power-user feature behind dashboards and dynamic indexes. Start simple (filter by `type`, `content`, or a tag) and build up. The block table columns are documented in the Admin Guide and the community wiki.

### 6.6 Tags, bookmarks, and the `siyuan://` protocol

- **Tags** — write `#tag#` to tag a block. Browse and rename tags from the **Tags** dock.
- **Bookmarks** — mark important blocks; browse them from the **Bookmarks** dock.
- **`siyuan://` links** — every block has a protocol URL you can copy and paste elsewhere (e.g. into another app) to deep-link straight back to that block in SiYuan.

---

## 7. Organizing: Notebooks, Documents, and Daily Notes

### 7.1 Notebooks

A **notebook** is a top-level container. Create one from the doc-tree header. You can:

- **Open / close** a notebook (closing hides it without deleting anything).
- Set a **notebook icon** and sort order.
- Configure per-notebook defaults: where new documents and reference-created documents are saved, and the daily-note path and template.

### 7.2 Documents

Documents live in a tree inside a notebook and can be nested. From the doc tree you can create, rename, move, duplicate, and delete documents, and drag to reorder. SiYuan supports deep nesting (by default it warns beyond 7 levels; this is configurable).

Useful document operations (available from the doc menu or block menu):

- **Heading → Document**: promote a heading and its content into its own document.
- **Document → Heading** / **List item → Document**: restructure between outline levels and documents.
- **Save as template**: turn a document into a reusable template.

### 7.3 Daily Notes

**Daily Notes** give you a dated journal entry per day. Each notebook can define its own daily-note storage path and template. The default path uses a date pattern like:

```text
/daily note/{{now | date "2006/01"}}/{{now | date "2006-01-02"}}
```

Open today's daily note with a single action (and bind it to a keyboard shortcut). Daily notes are ordinary documents, so you can reference and embed them like anything else — perfect for capturing fleeting thoughts that you later link into permanent notes.

---

## 8. Databases (Attribute Views)

SiYuan includes a built-in **database**, internally called an **attribute view**. A database block turns a collection of blocks into structured rows with typed columns — similar to a Notion database.

### 8.1 Creating a database

Insert a database block (from the block menu or the `/` slash menu). You then add **columns** (keys) of various types and **rows** (which can be new detached entries or existing blocks bound into the database).

### 8.2 Column (field) types

Databases support many field types, including text, number, select/multi-select, date, checkbox, URL, email, phone, relation (link to another database), rollup (aggregate across a relation), template (computed), and asset fields. Primary-key values identify each row.

### 8.3 Views

A single database can present its data through multiple **views**, each with its own filters, sorts, and visible columns. Available layouts include:

- **Table** view — the classic spreadsheet-style grid.
- **Gallery** view — card layout, good for image-heavy collections.
- **Kanban** view — columns grouped by a field value, for task boards.

Switch and configure views from the database toolbar. You can group rows, filter and sort, and reorder or hide columns per view.

> [!NOTE]
> Databases are blocks, so a single underlying database can be **mirrored** into several documents. Editing the data in one place updates every mirror.

### 8.4 Working with rows

- Add existing blocks to a database, or create new detached blocks with values pre-filled.
- Set field values inline; relation and rollup fields pull live data from linked databases.
- Export a database (for example to a spreadsheet) from its menu.

---

## 9. Search and Find/Replace

### 9.1 Full-text search

Open search to query across your whole knowledge base. SiYuan's search is block-aware and highly configurable in **Settings → Search**:

- **Block types to include** — documents, headings, lists, list items, code blocks, math blocks, tables, quotes, super blocks, paragraphs, HTML blocks, embed blocks, database blocks, audio/video/IFrame/widget blocks, callouts.
- **Attributes to search** — block name, alias, memo, and the inline attribute list (IAL).
- **Case sensitivity** and a **result limit** (default 64).
- **Asset content search** — optionally index the text inside attached files (PDFs, etc.) so you can search their contents.

### 9.2 Search scopes and methods

You can search the current document, a notebook, or everything, and combine keywords. Saved **search criteria** let you re-run complex queries. Specialized searches power the editor too: tag search, template search, widget search, reference-block search, and embed-block search.

### 9.3 Find and replace

Within a document (or a wider scope), use find/replace to make bulk edits. SiYuan replaces text across matching blocks while preserving block structure and references.

---

## 10. Flashcards and Spaced Repetition

SiYuan has a built-in spaced-repetition system powered by the **FSRS** algorithm (via the *riff* engine), so you can turn your notes into durable memory without a separate app.

### 10.1 Making cards

Turn content into flashcards directly from your notes. You can enable several card-making modes in **Settings → Flashcard**:

| Mode | What becomes a card |
|---|---|
| Mark | Marked content |
| List | List-block cards |
| Super block | Super-block cards |
| Heading | Heading-block cards |
| Deck | Cards added to a specific deck |

Add a block to a deck from its block menu; the block stays a normal note and also becomes a card.

### 10.2 Reviewing

Open the review interface to study due cards. SiYuan schedules each card with FSRS based on your ratings. You control:

- **New card limit** (default 20) and **review card limit** (default 200) per session.
- **Review mode**: mixed new/old, new-first, or old-first.
- **Request retention**, **maximum interval**, and FSRS **weights** — advanced tuning that the built-in optimizer can refine for you.

### 10.3 Decks

Cards can be organized into **decks**. You can review all due cards, the due cards for a notebook, or the due cards within a document tree.

---

## 11. Templates and Snippets

### 11.1 Document templates

Templates let you stamp out new documents with a predefined structure. SiYuan templates use the **Sprig** template engine, so you can include dynamic values like the current date, computed paths, and more.

- Save any document as a template (it lands in `data/templates/`).
- Insert a template into the current document, or set a template as a notebook's daily-note template.
- Use template functions for dates, strings, and math — for example the daily-note date pattern shown earlier.

### 11.2 Code snippets (JavaScript / CSS)

Snippets let you customize SiYuan's behavior and appearance without installing a plugin:

- **CSS snippets** restyle the interface or printed/exported output.
- **JavaScript snippets** run custom logic in the app.

Manage them in **Settings → Snippets** (you can enable/disable CSS and JS globally, and toggle each snippet, including whether it applies in the publish service).

> [!CAUTION]
> JavaScript snippets and plugins run with access to the app. Only add snippets and plugins from sources you trust.

---

## 12. The Marketplace (Bazaar)

The **Bazaar** is SiYuan's community marketplace. Browse and install community-made extensions directly from within the app:

| Package type | What it adds |
|---|---|
| **Plugins** | New features and integrations (built on the *petal* plugin API) |
| **Widgets** | Embeddable mini-apps inside your notes |
| **Themes** | Light/dark visual themes |
| **Icons** | Icon sets for the UI |
| **Templates** | Ready-made document templates |

For each package you can view its README, install it, update it, or uninstall it. Installed packages live under your `data/` folder (`plugins/`, `widgets/`, `templates/`, and the appearance folders for themes/icons).

> [!NOTE]
> Plugins require a compatible SiYuan version. If a plugin says it needs a newer version, update SiYuan first. You can enable or disable individual plugins, and globally disable the plugin system (the "petal" system) if you prefer a stock experience.

> [!TIP]
> You can update all installed marketplace packages in a batch from the Bazaar, and SiYuan will tell you which packages have updates available.

---

## 13. Import and Export

### 13.1 Importing

| Import | How |
|---|---|
| Standard Markdown file(s) | Import a `.md` file or a folder of Markdown |
| Markdown ZIP | Import a `.zip` archive of Markdown + assets |
| SiYuan `.sy` data | Import another SiYuan document/notebook export |
| Full data archive | Settings → Export → Import Data restores a previously exported data folder |

> [!NOTE]
> Markdown import is available on the desktop app. The Docker/browser deployment does not support importing Markdown files.

### 13.2 Exporting

SiYuan exports to a remarkably wide range of formats. Many formats are produced through **Pandoc**, which the desktop app bundles.

**Common formats**

- **Markdown** — standard Markdown with assets (with options for block-ref handling, YAML front matter, removing asset-ID suffixes, including sub-documents).
- **PDF** — with configurable footer (default `%page / %pages`) and optional watermark.
- **Word (`.docx`)** and **HTML** (in-app preview HTML, standalone HTML, or browser HTML).
- **SiYuan `.sy`** — for moving content between SiYuan workspaces losslessly.

**Additional formats (via Pandoc)**

reStructuredText, AsciiDoc, Textile, OPML, OrgMode, MediaWiki, OpenDocument Text (`.odt`), RTF, and EPUB. You can also export a single code block or an attribute view (database), and **copy to** third-party platforms such as WeChat MP, Zhihu, and Yuque.

> [!WARNING]
> Export to PDF, HTML, and Word is **not** available in the Docker/browser deployment — those rely on the desktop runtime. Use the desktop app for those formats.

### 13.3 Export options worth knowing

In **Settings → Export** you can control how references and embeds are rendered on export (for example, block references can become anchor-text links, plain anchor text, or footnotes), whether titles are added, tag markers, Pandoc binary/parameters, and watermark settings for PDF and image exports.

---

## 14. Web Clipping

Capture web content straight into SiYuan with the official browser extension:

- Install the **SiYuan** extension for Chrome/Edge (see [siyuan-note/siyuan-chrome](https://github.com/siyuan-note/siyuan-chrome)).
- Clip a full page, a selection, or a simplified article into a notebook of your choice.
- Clipped network images can be downloaded into your local `assets/` so your notes stay self-contained.

SiYuan can also convert network images and network-referenced assets in a document into local assets after the fact, so a clipped or pasted note becomes fully offline.

---

## 15. AI Assistant

SiYuan integrates with the **OpenAI API** (and OpenAI-compatible / Azure OpenAI endpoints) for AI writing and Q&A chat.

### 15.1 Setting it up

In **Settings → AI** provide your API key and (optionally) a custom base URL, model, proxy, timeout, temperature, max tokens, and how many previous messages to include as context. Sensible defaults are provided (for example, a default temperature of `1.0` and 7 context messages).

> [!TIP]
> Because the base URL is configurable, you can point SiYuan's AI at any OpenAI-compatible provider or a local gateway, not just OpenAI itself.

### 15.2 Using AI

With AI configured, you can:

- Run **AI actions** on selected blocks (summarize, translate, continue writing, custom prompts, etc.).
- Have a **chat** conversation that uses your selected content as context.

> [!NOTE]
> The AI feature sends the relevant content to whatever API endpoint you configure. If you require strict privacy, point it at a self-hosted or local model, or leave it disabled.

---

## 16. Synchronization and Backup

SiYuan keeps your data local first, then syncs an **encrypted** copy to the destination you choose. Under the hood, sync is built on the **data repo** (*dejavu*), which versions your data into snapshots much like a version-control system.

### 16.1 The data repo and the repo key

Before you can sync or take cloud snapshots, you initialize a **data repo key** — an AES encryption key. All data is encrypted with this key before it leaves your device.

> [!IMPORTANT]
> Your repo key is the only way to decrypt synced data. Back it up. On each device, set the **same** key (Settings → About → Data repo key). If you lose it and your devices' keys are inconsistent, you may have to reset the repo and re-initialize — see the [FAQ](#21-faq).

### 16.2 Sync providers

| Provider | Description |
|---|---|
| **SiYuan Cloud** | Official cloud service (a paid membership privilege) |
| **S3** | Any S3-compatible object storage (endpoint, bucket, region, keys, path-style option) |
| **WebDAV** | Any WebDAV server (endpoint, username, password) |
| **Local file system** | A local/NAS directory you control |

Configure the provider, enable sync, and choose a **sync mode**: automatic (on an interval, default 30s), manual, or fully manual. You can also enable **perception** (sync awareness) and choose whether conflicts generate a conflict document.

### 16.3 Snapshots

Independently of cloud sync, you can take **snapshots** of your data repo, tag them, browse them, diff them, and roll individual files (or whole snapshots) back. This gives you point-in-time recovery entirely on your own machine. SiYuan can also automatically purge old local indexes to save space.

> [!TIP]
> Take a tagged snapshot before any big reorganization. If something goes wrong, you can roll back to exactly that point.

### 16.4 Third-party cloud storage vs. third-party sync disks

SiYuan **supports** syncing to third-party *cloud storage* (S3/WebDAV) but does **not** support storing your workspace inside a third-party *sync disk* that syncs files independently — that risks corruption. The distinction matters: SiYuan controls the upload/download of encrypted snapshots; a sync disk would race with SiYuan's own file writes.

---

## 17. Appearance and Customization

In **Settings → Appearance** you can tune the look and feel:

- **Mode**: light or dark, optionally **following the OS** automatically.
- **Themes**: choose separate light and dark themes (defaults: `daylight` and `midnight`); install more from the Bazaar.
- **Code-block themes** for light and dark (defaults: `github` and `base16/dracula`).
- **Icon set** (default `material`; `ant` and others available).
- **Interface language** — many languages are supported (English, Chinese, Japanese, German, Spanish, French, Korean, and more).
- **Close-button behavior** (desktop): quit, or minimize to the system tray.
- **Status bar** visibility and content.

You can further customize with **CSS/JS snippets** (see [Templates and Snippets](#11-templates-and-snippets)) and **themes/icons** from the Bazaar.

Editor behavior is highly configurable in **Settings → Editor** too — font size and family, code-block options (line numbers, wrap, ligatures, tab width), full-width vs. fixed-width layout, spellcheck, RTL, KaTeX macros, virtual references, float-window (hover preview) behavior, and how many blocks load dynamically.

### 17.1 Keyboard shortcuts

SiYuan ships a full keymap that you can fully customize in **Settings → Keymap**. Common defaults include <kbd>Ctrl</kbd>+<kbd>/</kbd> for the block menu and a configurable global shortcut to show/hide the main window. Rebind anything to match your habits.

---

## 18. Common Workflows

Recipes that combine the features above.

### 18.1 A daily capture + permanent notes workflow

- [ ] Bind a global shortcut to open today's **Daily Note**.
- [ ] Throughout the day, dump quick thoughts as blocks in the daily note.
- [ ] When an idea matures, move (drag) the block into a permanent document — references follow it.
- [ ] Link related permanent notes with `((` references; review **Mentions** to discover implicit links and promote them.

### 18.2 A project dashboard with SQL embeds

- [ ] Tag project blocks with `#projectX#`.
- [ ] In a project hub document, add an **embed** with a SQL query selecting all `#projectX#` blocks, ordered by updated date.
- [ ] Add a second embed for open task-list items so the hub doubles as a to-do list.

### 18.3 Studying with flashcards

- [ ] As you write notes, add key facts to a **deck** from the block menu.
- [ ] Each day, open **Review** and study due cards.
- [ ] Let the FSRS optimizer tune your weights after you've accumulated review history.

### 18.4 A structured database of reading

- [ ] Create a **database** with fields: Title (primary), Author (text), Status (select), Rating (number), Link (URL), Notes (relation to a notes database).
- [ ] Add a **Kanban** view grouped by Status and a **Table** view sorted by Rating.
- [ ] Mirror the database into your dashboard document.

### 18.5 Multi-device with encrypted sync

- [ ] On device A, initialize the **data repo key** and configure a sync provider (S3/WebDAV/Cloud).
- [ ] On device B, set the **same** repo key and the same provider, then sync.
- [ ] Use automatic sync, and take a tagged **snapshot** before major edits.

---

## 19. How SiYuan Works (Concepts)

You don't need this to use SiYuan, but understanding the model explains its behavior.

### 19.1 Kernel + UI

SiYuan is split into a **kernel** (a local engine) and a **UI**. The kernel stores your files, parses Markdown, maintains a search index, handles sync, renders databases, runs the AI and OCR features, and exposes everything over a local HTTP/WebSocket interface. The UI — whether a desktop window, a mobile screen, or a browser tab — talks to that local kernel. On desktop and mobile the kernel is bundled and started for you automatically; you never manage it directly.

### 19.2 Why blocks have IDs

Every block gets a stable unique ID when created. References, embeds, attributes, flashcards, and the search index all point at IDs, not at text or file positions. That's why you can move, rename, and restructure freely without breaking links.

### 19.3 The block index

The kernel keeps a SQLite index of every block (content, type, attributes, relationships). This index is what makes instant full-text search and SQL query embeds possible. If the index ever drifts from your files, you can rebuild it (see Troubleshooting); your `.sy` files remain the source of truth.

### 19.4 Markdown engine

SiYuan's editing and rendering are powered by **Lute**, a Markdown engine maintained alongside SiYuan. It implements the block-style, Kramdown-attribute-aware flavor of Markdown that SiYuan uses, which is why SiYuan can be WYSIWYG and still store standard-ish Markdown.

### 19.5 Encrypted, versioned sync

Sync doesn't copy raw files to the cloud. The **data repo** chunks and encrypts your data into content-addressed snapshots (the *dejavu* engine), then uploads only what changed. This makes sync efficient and keeps your plaintext off the server.

---

## 20. Troubleshooting

Each entry lists the exact message or symptom, the likely cause, the fix, and how to avoid it.

### Symptom: SiYuan won't start — "The database is unavailable"

- **Cause**: The kernel can't open its database file (permissions, disk, or a corrupt index).
- **Solution**: Check `workspace/temp/siyuan.log` for the detailed error. Ensure the workspace folder is writable and not on a failing/full disk. If the index is corrupt, rebuild it from **Settings** (rebuild index) once the app starts.
- **Prevention**: Keep enough free disk space and don't place the workspace on unreliable network/removable storage.

### Symptom: "The workspace is locked"

- **Cause**: Another SiYuan kernel process is already using this workspace, or a previous one didn't exit cleanly.
- **Solution**: End the `SiYuan-Kernel` process in your OS task manager (or restart the OS), then start SiYuan again.
- **Prevention**: Let SiYuan close fully before reopening; avoid opening the same workspace from two apps at once.

### Symptom: "Failed to create workspace directory" / insufficient permissions

- **Cause**: The workspace folder lacks write permissions (common with Docker bind mounts and mismatched UID/GID).
- **Solution**: Fix ownership of the workspace folder. On the desktop, choose a workspace location you own. For Docker, set `PUID`/`PGID` to match the host folder owner. See `workspace/temp/siyuan.log`.
- **Prevention**: Align folder ownership with the user running SiYuan.

### Error: `Load bazaar package's README ... failed` / `get bazaar package failed, please check your network`

- **Cause**: SiYuan can't reach the marketplace (network/proxy issue) when fetching a package or its README.
- **Solution**: Check your internet connection and any proxy settings (**Settings → About / network proxy**). Retry later.
- **Prevention**: Configure the network proxy if you're behind a firewall.

### Error: `require upgrade SiYuan to use this plugin [...]`

- **Cause**: The plugin needs a newer SiYuan version than you have installed.
- **Solution**: Update SiYuan, then install/enable the plugin.
- **Prevention**: Keep SiYuan up to date before installing fresh plugins.

### Symptom: S3 sync fails — `put chunk failed:`

- **Cause**: Object-storage credentials, endpoint, region, bucket, or path-style settings are wrong, or the network/TLS handshake failed.
- **Solution**: Re-check your S3 endpoint, access/secret keys, bucket, and region in **Settings → Sync**. Try toggling **path style**; if your endpoint uses a self-signed certificate you may need **skip TLS verify**. Confirm the bucket exists and the keys can write to it.
- **Prevention**: Test credentials with an S3 client first; keep timeouts reasonable.

### Symptom: Sync conflict / duplicate "conflict" documents appear

- **Cause**: The same data changed on two devices before they synced.
- **Solution**: Open the generated conflict document(s), merge the content you want, and delete the rest. Enable **generate conflict doc** so you never silently lose an edit.
- **Prevention**: Let one device finish syncing before editing on another; use automatic sync.

### Symptom: A block's gutter (block icon) is missing

- **Cause**: For the first sub-block under a list item, the gutter icon is intentionally omitted.
- **Solution**: Click into the block and press <kbd>Ctrl</kbd>+<kbd>/</kbd> to open its block menu.
- **Prevention**: N/A — this is by design.

### Error: `not found executable pandoc`

- **Cause**: An export format that needs Pandoc was requested, but Pandoc isn't available (custom Pandoc path, or the headless/Docker deployment).
- **Solution**: Use the desktop app (which bundles Pandoc), or set a valid Pandoc binary path in **Settings → Export**.
- **Prevention**: Remember that Pandoc-based and PDF/Word/HTML exports require the desktop runtime.

### Error: `[...] is not sub path of workspace` / `refuse to export sensitive file`

- **Cause**: SiYuan refuses to serve or export files outside your workspace or files it considers sensitive — a safety guard.
- **Solution**: Keep referenced assets inside the workspace `assets/` folder. Re-insert the asset locally if it lives elsewhere.
- **Prevention**: Use **insert local assets** / **convert network assets to local** so files live under the workspace.

### Symptom: Search misses content you know exists

- **Cause**: The relevant block type or attribute is excluded from search, the result limit is too low, or the index is stale.
- **Solution**: In **Settings → Search**, enable the block types/attributes you want and raise the limit. Rebuild the index if results still seem wrong.
- **Prevention**: Configure search scope once to match how you write.

---

## 21. FAQ

**Q: How does SiYuan store my data?**
Everything is in your workspace's `data/` folder: notebooks (with `.sy` JSON documents), plus `assets/`, `emojis/`, `snippets/`, `storage/`, `templates/`, `widgets/`, `plugins/`, and `public/`. Your notes are plain files you can copy and back up.

**Q: Can I keep my workspace in Dropbox/OneDrive/iCloud/Syncthing?**
No. Third-party file-sync disks can corrupt SiYuan data because they sync files independently of SiYuan's writes. Use SiYuan's own sync (Cloud/S3/WebDAV/Local) instead. You *can* sync to third-party cloud *storage* (S3/WebDAV) — that's different from a sync disk.

**Q: Is SiYuan open source?**
Yes — the UI and kernel are open source under AGPLv3, as are the Android, iOS, HarmonyOS, and Chrome-clipping projects.

**Q: Do I have to pay?**
Most features are free, even for commercial use. Some privileges (notably the official cloud sync/storage) require a paid membership. See the [pricing page](https://b3log.org/siyuan/en/pricing.html).

**Q: How do I upgrade?**
If installed via an app store, update there. If installed via the desktop installer, enable **Settings → About → Automatically download update installation package**, or download the latest installer manually. Check your version under **Settings → About**.

**Q: What if I lose my data repo key?**
If your devices were correctly initialized with the same key, copy it from **Settings → About → Data repo key**. If keys are inconsistent or all devices are unavailable: back up your data (Export Data or copy `workspace/data/`), then **Reset data repo**, re-initialize the key on one device, and import it on the others. Old cloud sync directories and snapshots will no longer be usable and can be deleted.

**Q: Can other people access my self-hosted instance?**
Only if you let them. Set a strong **access auth code**, and understand the role-based access and publish service described in the Admin Guide before exposing SiYuan beyond localhost.

**Q: Does SiYuan work offline?**
Yes — it's local-first. Sync, AI, OCR-via-cloud, and the marketplace need network access, but reading and writing your notes does not.

---

## 22. Reference

### 22.1 Feature summary

| Area | Highlights |
|---|---|
| Editor | Block-style Markdown WYSIWYG, million-word docs, block zoom, math, diagrams, code highlighting |
| Linking | Block references, backlinks & mentions, virtual references, embeds, tags, bookmarks, `siyuan://` |
| Organization | Notebooks, nested documents, daily notes, outline |
| Database | Attribute views with table/gallery/kanban, typed fields, relations, rollups, mirroring |
| Study | Flashcards with FSRS spaced repetition, decks |
| Reuse | Sprig templates, JS/CSS snippets |
| Marketplace | Plugins, widgets, themes, icons, templates |
| Import/Export | Markdown, PDF, Word, HTML, EPUB, OPML, OrgMode, RST, AsciiDoc, Textile, MediaWiki, ODT, RTF |
| Capture | Web clipping (Chrome/Edge), local-asset conversion |
| AI | OpenAI / OpenAI-compatible / Azure chat and actions |
| Sync & backup | Encrypted data repo, snapshots, SiYuan Cloud / S3 / WebDAV / Local |
| Platforms | Windows, macOS, Linux, Android, iOS, HarmonyOS, Docker (browser) |

### 22.2 Default workspace layout

```text
~/SiYuan/                 (or your chosen workspace)
├── conf/                 settings (conf.json)
├── data/
│   ├── <notebook>/       .sy documents
│   ├── assets/           images, PDFs, attachments
│   ├── emojis/  snippets/  storage/  templates/  widgets/  plugins/  public/
├── history/              file-history snapshots
├── repo/                 encrypted data repo (sync/snapshots)
└── temp/                 caches and logs (siyuan.log)
```

### 22.3 Notable defaults

| Setting | Default |
|---|---|
| Editor font size | 16 |
| History generation interval | 10 minutes |
| History retention | 30 days |
| Daily-note path | `/daily note/YYYY/MM/YYYY-MM-DD` (date-pattern) |
| Search result limit | 64 |
| New / review card limits | 20 / 200 |
| Auto-sync interval | 30 seconds |
| Light / dark theme | `daylight` / `midnight` |
| Light / dark code theme | `github` / `base16/dracula` |
| Icon set | `material` |
| Kernel HTTP port (server) | `6806` |
| Publish service port | `6808` |

### 22.4 Ecosystem and related projects

| Project | Role |
|---|---|
| [lute](https://github.com/88250/lute) | Markdown editor engine |
| [dejavu](https://github.com/siyuan-note/dejavu) | Encrypted, versioned data repo (sync/snapshots) |
| [riff](https://github.com/siyuan-note/riff) | Spaced-repetition (FSRS) engine |
| [bazaar](https://github.com/siyuan-note/bazaar) | Community marketplace |
| [petal](https://github.com/siyuan-note/petal) | Plugin API |
| [siyuan-chrome](https://github.com/siyuan-note/siyuan-chrome) | Web-clipping browser extension |
| [siyuan-android](https://github.com/siyuan-note/siyuan-android) / [ios](https://github.com/siyuan-note/siyuan-ios) / [harmony](https://github.com/siyuan-note/siyuan-harmony) | Mobile apps |

### 22.5 Where to get help

- English discussion forum: [liuyun.io](https://liuyun.io)
- Awesome SiYuan (community resources): [siyuan-note/awesome](https://github.com/siyuan-note/awesome)
- Discord and the GitHub repository for issues and roadmap.

---

_Generated June 2026 from siyuan-note/siyuan at 96dfe0b. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._