SiYuan is a local-first knowledge workspace built from addressable content blocks. A workspace contains notebooks, documents, assets and configuration. Paragraphs, headings and list items receive block identities that links and backlinks can follow after the user reorganizes content. SiYuan stores notebook documents as .sy JSON files rather than ordinary Markdown source files.
Blocks and files are different layers
A block reference connects to the identity of a paragraph or another content block. It does not copy that block into the current document. Backlinks and graph views use the same relationships. Database-style fields and structured views add another organization layer over the documents.
The .sy file is internal block storage. Editing it as if it were a Markdown document can damage structure or metadata. Markdown, HTML and office-document representations come from explicit export workflows. Export creates external output; it does not change the workspace into a folder that another Markdown editor can safely modify in place.
The workspace has core and rebuildable areas
A valid workspace root contains configuration and a data directory for notebooks. It also separates snapshots, edit history, temporary indexes, caches, queues and quarantined corrupted data. Copying only the temporary directory does not back up notebook content, while deleting rebuildable indexes does not remove the core documents.
The workspace lock prevents two SiYuan kernels from opening the same workspace at once. That restriction protects concurrent writes. Removing or bypassing the lock while another kernel still runs can let both processes change the same internal files, which defeats the protection the lock provides.
Third-party folder sync can corrupt live data
The project explicitly rejects placing the active workspace inside a third-party synchronization-disk folder. Those services can reorder, duplicate or partially merge internal files while SiYuan is writing them. Built-in synchronization and snapshots understand the workspace model; a generic folder service does not.
The data repository uses a key for synchronization history. If every configured device loses that key, the documented reset begins with a manual backup, creates a new repository key and switches to a new cloud sync directory. Old cloud snapshots become unavailable after the reset. A forgotten key therefore changes the synchronization lineage rather than producing an ordinary password-reset result.
Self-hosting requires an access secret
A self-hosted SiYuan kernel can expose the workspace through a network port. The default or unchanged access-authentication code does not protect an Internet-reachable instance adequately; anyone who reaches it may access the data. The deployment needs a changed secret and a network boundary appropriate to the intended users.
Workspace-level configuration and notebook-level configuration have different scopes. Moving one file into the wrong directory does not apply its setting globally. Before a migration, the useful backup includes the core data and the configuration needed to interpret it, followed by a test opening in a separate workspace rather than a live synchronized folder.
