Noureddine RAMDI / SiYuan: A modular, privacy-first self-hosted knowledge management system with a TypeScript and Go hybrid stack

Created Sat, 02 May 2026 20:07:04 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1166 Words
github-stars typescript go self-hosted knowledge-management docker modular

siyuan-note/siyuan

SiYuan is a personal knowledge management system that stands out by combining privacy-first principles with a modular architecture and a hybrid tech stack of TypeScript and Go. It caters to users who want to self-host their note-taking and knowledge base, providing fine-grained control over their data and a rich editing experience. The project’s architecture and feature set make it a compelling choice for developers and power users looking to run a performant, extensible PKM platform without relying on cloud services.

What SiYuan does and its architecture

At its core, SiYuan is a self-hosted, privacy-focused personal knowledge management system designed to handle complex note-taking workflows. It supports block-level referencing, meaning you can link to and embed individual blocks of content rather than whole pages, a feature that enables precise knowledge graph construction and flexible content reuse.

The editor supports Markdown WYSIWYG editing, blending the convenience of rich text editing with the portability of Markdown. Beyond basic notes, SiYuan integrates advanced features such as embedding SQL queries to manipulate and display data dynamically, spaced repetition flashcards for learning, and even AI writing assistants to help generate content.

Architecturally, SiYuan is split into multiple projects: a TypeScript-based frontend editor engine, a marketplace for plugins and themes, and mobile apps for iOS and Android. The backend is written in Go, providing performance and concurrency benefits critical for handling data management and synchronization efficiently.

This hybrid stack leverages TypeScript’s ecosystem and developer experience on the client side while relying on Go’s robustness for backend services. The modularity allows independent development and deployment of components, improving maintainability and scalability.

SiYuan supports Docker deployment, simplifying installation and updates in self-hosted environments. Data and configuration are stored locally, reinforcing the privacy-first stance.

What sets SiYuan apart technically

SiYuan’s most distinctive technical aspect is its hybrid architecture that separates concerns cleanly: the frontend in TypeScript provides a rich, reactive UI with modern web technologies, while the Go backend handles the heavy lifting around data storage, indexing, and synchronization.

The choice of Go for the backend is pragmatic; it offers concurrency primitives and static typing, which help build a stable, performant server capable of handling multiple users or large datasets. Meanwhile, TypeScript ensures type safety and tooling support on the frontend, which is crucial for complex UI logic like a WYSIWYG Markdown editor that also manages block-level references.

The modular design means the codebase is split into multiple repositories or subprojects, each focusing on a distinct domain such as the editor core, marketplace, or mobile clients. This separation helps keep the code clean and allows contributors to focus on specific areas without wading through unrelated code.

Tradeoffs include the inherent complexity of maintaining two languages and coordinating releases across components. Developers contributing to SiYuan need familiarity with both TypeScript and Go, which can raise the barrier for new contributors. However, this approach balances DX and runtime performance well.

Feature-wise, embedding SQL queries and supporting spaced repetition flashcards within a PKM tool is not common and illustrates SiYuan’s aim to be more than a note-taking app — it’s a platform for knowledge work and learning.

Quick start

It is recommended to prioritize installation through the application market on desktop and mobile for easy upgrades:

App Market

Mobile:

  • App Store
  • Google Play
  • F-Droid

Desktop:

  • Microsoft Store

Installation Package

  • B3log
  • GitHub

Package Manager

siyuan

siyuan-note

Docker Hosting

Docker Deployment

Overview

The easiest way to serve SiYuan on a server is to deploy it through Docker.

  • Image name b3log/siyuan

  • Image URL

File structure

The overall program is located under /opt/siyuan/, which is basically the structure under the resources folder of the Electron installation package:

  • appearance: icon, theme, languages
  • guide: user guide document
  • stage: interface and static resources
  • kernel: kernel program

Entrypoint

The entry point is set when building the Docker image: ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]. This script allows changing the PUID and PGID of the user that will run inside the container. This is especially relevant to solve permission issues when mounting directories from the host. The PUID (User ID) and PGID (Group ID) can be passed as environment variables, making it easier to ensure correct permissions when accessing host-mounted directories.

Use the following parameters when running the container with docker run b3log/siyuan:

  • --workspace: Specifies the workspace folder path, mounted to the container via -v on the host
  • --accessAuthCode: Specifies the access authorization code

More parameters can be found using --help. Here’s an example of a startup command with the new environment variables:

docker run -d \
  -v workspace_dir_host:workspace_dir_container \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  b3log/siyuan \
  --workspace=workspace_dir_container \
  --accessAuthCode=xxx
  • PUID: Custom user ID (optional, defaults to 1000 if not provided)
  • PGID: Custom group ID (optional, defaults to 1000 if not provided)

How to explore the project

If you want to dive deeper, the repository is organized into several key components:

  • Editor engine: The heart of the UI and editing experience, implemented in TypeScript.
  • Marketplace: A platform to install plugins and themes, which extends SiYuan’s capabilities.
  • Mobile apps: Native clients for iOS and Android to keep your data synced on the go.

The README and user guides under the guide folder provide detailed documentation on features and usage. The kernel folder contains the backend logic primarily written in Go. The app supports rich customization through themes and language packs in the appearance folder.

Verdict

SiYuan is a solid choice if you want a self-hosted, privacy-first knowledge management system that supports advanced workflows like block-level referencing and spaced repetition. Its hybrid TypeScript and Go architecture balances user experience and backend performance, though it introduces complexity in development and deployment.

The modular design allows for extensibility but may require some learning curve to contribute or customize deeply. Docker support simplifies hosting, making it accessible for users comfortable with containerization.

If you value privacy, control over your data, and need a feature-rich PKM tool beyond simple note-taking, SiYuan is worth exploring. However, for casual users or those who prefer a single-language stack, the technical overhead and evolving ecosystem might feel heavy. Still, the project is actively maintained and demonstrates a thoughtful approach to building a modern self-hosted knowledge platform.

→ GitHub Repo: siyuan-note/siyuan ⭐ 42,990 · TypeScript