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
2. Installation
3. Core Concepts
4. The Workspace and Your Data
5. Writing in the Editor
6. Blocks, References, and Links
7. Organizing: Notebooks, Documents, and Daily Notes
8. Databases (Attribute Views)
9. Search and Find/Replace
10. Flashcards and Spaced Repetition
11. Templates and Snippets
12. The Marketplace (Bazaar)
13. Import and Export
14. Web Clipping
15. AI Assistant
16. Synchronization and Backup
17. Appearance and Customization
18. Common Workflows
19. How SiYuan Works (Concepts)
20. Troubleshooting
21. FAQ
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 or GitHub 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, Google Play, or F-Droid.
2. Open the app; it creates a workspace inside the app's data directory.

Self-hosted (Docker, browser access)

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

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

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.

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.

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

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:

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

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.

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:

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 Ctrl+/ 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 Ctrl+/ 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.

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:

/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:

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:

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

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).
• 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.

16.2 Sync providers

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) 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 Ctrl+/ 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 Ctrl+/ 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.

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

22.2 Default workspace layout

~/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

22.4 Ecosystem and related projects

22.5 Where to get help

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