SiYuan: A Local-First Note Tool That Doesn't Lock You In

You've probably tried a note-taking app that promised to be your "second brain," only to find your notes trapped in a proprietary format you can't easily export. Or maybe you've worried about what happens to years of your writing if the company behind the app shuts down. SiYuan takes a different approach: it stores your data locally and lets you sync it however you want.

What It Does

SiYuan is a block-based note-taking tool. Instead of treating notes as monolithic documents, it treats them as collections of blocks—paragraphs, list items, headings, and so on. This block-level structure is the foundation for how you organize and reference content within the app.

The project is open source under AGPLv3 and has accumulated a substantial following, with distribution through Docker, package managers, and various hosting platforms including Kubernetes, Unraid, and TrueNAS. It's available in multiple languages including English, Chinese, Japanese, and Turkish. The README describes its tagline as "From thought to insight, with agents," suggesting some integration with AI or automation tools, though the truncated README doesn't elaborate on specifics.

Architecturally, the key detail is in the FAQ: SiYuan stores data locally. This isn't a cloud-first app with a local cache—it's local-first with optional sync. That distinction matters for anyone who's been burned by data lock-in before.

Why It's Cool

• Your data stays yours. The local storage model means you're not dependent on someone else's servers to access your notes. If the project disappeared tomorrow, your data would still be on your machine in a format you can work with. That's not a small thing when you're talking about years of accumulated thinking.

• Sync on your terms. The FAQ specifically addresses whether you can sync through third-party sync disks—which suggests the answer is yes. You're not forced into a proprietary sync service. Use Dropbox, Syncthing, a Git repo, or whatever else fits your workflow. This is the kind of flexibility that power users actually want.

• Block-based means block-based. Many apps claim to be block-based but really just mean "we have a slash command menu." SiYuan's architecture treats blocks as first-class citizens. The FAQ even addresses a specific edge case about finding block icons for paragraph blocks inside list items—the kind of detail that only matters if blocks are genuinely central to how the app works.

• Deployment flexibility. You can run SiYuan as a desktop app, in Docker, on Kubernetes, on Unraid, or on TrueNAS. That's an unusual spread of options that covers everyone from casual users to homelab enthusiasts running a personal server rack.

• Open source with real momentum. The README shows active development—recent commits, closed pull requests, and a presence on Trendshift. AGPLv3 isn't the most permissive license, but it ensures the project stays open.

How to Try It

Getting started depends on how you want to run it:

1. Desktop app: Download an installation package from the releases page. This is the simplest option if you just want to try it on your local machine.

2. Package manager: The README mentions package manager installation, though specific commands aren't included in the truncated version. Check the repository for your platform's package manager.

3. Docker: If you prefer running things in containers, pull the image from Docker Hub:

   docker pull b3log/siyuan
   

   The README also covers Kubernetes, Unraid, and TrueNAS hosting if you want to run it on a home server or NAS.

4. Command-line interface: There's a CLI available, which is useful for automation or headless setups.

Once installed, you'll want to check the FAQ for details on data storage and upgrading. The repository is at github.com/siyuan-note/siyuan.

Final Thoughts

SiYuan is for people who've thought seriously about where their notes live and who controls them. If you're happy with a cloud service that handles everything for you, this might feel like unnecessary complexity. But if you want ownership over your data, the ability to sync however you choose, and a block-based structure that actually means something, it's worth a look. The range of deployment options—from desktop to Docker to Kubernetes—shows the project takes different workflows seriously. It's not trying to be everything to everyone, but for the right user, it's a solid fit.

Follow @githubprojects for more developer tools and open source projects.