SiYuan

SiYuan is a self‑hosted, privacy‑first knowledge‑management system that blends block‑based editing, hierarchical outlines, and bidirectional links into a single desktop application. At its core, the platform stores data in plain Markdown files augmented with metadata blocks that encode relations, properties, and custom fields. This lightweight representation allows the engine to perform full‑text search, graph traversal, and incremental sync without a heavyweight database layer. For developers, SiYuan presents an opportunity to build on top of a deterministic file‑system API while leveraging its robust plugin architecture.

Key Features

• Block & Outline Engine – Each note is a collection of blocks; outlines are treated as ordered block trees, enabling efficient diffing and rendering.
• Bidirectional Linking – Links are stored as block references, allowing the core to generate link graphs on demand and expose them via a JSON API.
• End‑to‑End Encryption – Data is encrypted locally before any remote sync, using AES‑256 and optional key‑management hooks for custom backends.
• Cross‑Platform Desktop – Built with Electron and Vue, the UI is consistent across Windows, macOS, and Linux while keeping a small footprint (~30 MB).
• Extensible Plugin System – Plugins are simple JavaScript modules that register UI components, commands, and data hooks through a well‑defined lifecycle.

Technical Stack

The bifurcated stack—Go for performance‑critical file handling and Electron/Vue for a responsive UI—offers developers a clear boundary: tweak the engine in Go or extend the UI/logic in JavaScript.

Core Capabilities & APIs

• RESTful API – Exposes CRUD operations on blocks, outlines, and files over http://localhost:6806/api. Endpoints support filtering by tags, timestamps, and link targets.
• WebSocket Hooks – Real‑time notifications for block changes, enabling live collaboration or external dashboards.
• Plugin Hooks – onInit, onBlockAdd, onCommandExecute callbacks allow deep integration with the editor lifecycle.
• CLI – siyuan-cli provides batch operations (e.g., bulk link resolution, export to PDF) and can be scripted in CI pipelines.

These interfaces make SiYuan suitable for building custom data pipelines, embedding knowledge graphs into larger systems, or exposing content to other applications.

Deployment & Infrastructure

SiYuan ships as a native binary for each platform, but the project also offers official Docker images (b3log/siyuan). Containers expose a single port for the API and mount a volume for data persistence. The lightweight nature of the binaries (under 50 MB) and the file‑based storage model mean that scaling is achieved by running multiple instances behind a reverse proxy or clustering the sync layer. For high‑availability, developers can orchestrate replicas with Docker Compose or Kubernetes, leveraging the stateless API and shared storage volumes.

Integration & Extensibility

• Plugin Marketplace – A curated list of community plugins is available in the app, but developers can also publish their own to GitHub or npm.
• Webhooks – External services (e.g., CI/CD, chatops) can listen to block change events and trigger actions.
• Custom Sync Adapters – The sync protocol is pluggable; developers can implement adapters for cloud storage, Git, or even custom peer‑to‑peer networks.
• Theming & UI Overrides – Vue components can be overridden or extended, allowing teams to brand the editor for internal use.

Developer Experience

The project’s documentation is organized around architecture, API reference, and plugin development guides. A dedicated docs/ directory contains Markdown files that are themselves part of the knowledge base, showcasing meta‑documentation. Community support is active on Discord and GitHub Discussions, with a rapid issue triage cycle. The AGPLv3 license encourages open‑source contributions while protecting the core from proprietary forks.

Use Cases

• Internal Knowledge Base – Companies can host SiYuan on a private server, encrypt data end‑to‑end, and expose a REST API for integration with internal tools.
• Data Lake Connector – Use the CLI and plugin hooks to ingest structured data (CSV, JSON) into block format for analysis.
• Live Collaboration Layer – Combine the WebSocket API with a custom front‑end to create real‑time document editing in web or mobile apps.
• Personal Knowledge Vault – A single-user instance running on a NAS, with automatic sync to encrypted cloud storage via custom adapters.

Advantages for Developers

• Performance – Go‑based engine ensures low latency file operations; no heavyweight DB keeps startup time minimal.
• Flexibility – File‑based storage allows developers to integrate with existing tooling (git, backup scripts) without migration hassles.
• Open Source & Extensible – AGPLv3 guarantees that