This Simple Container Turned My Markdown Files Into a Searchable Wiki

I have about 400 markdown files spread across six git repos, two cloud drives, and a folder called notes-from-2023 I have not opened in two years. The files are not organized. Half of them have a # Title heading, half do not. Some have frontmatter (structured metadata at the top of the file in YAML format), some do not. I have not been able to search across them since 2022, when my last attempt at a note system collapsed under its own weight.

A small Docker container called SiYuan (a personal knowledge base) changed this. It is a self-hosted, local-first, privacy-respecting note app that reads markdown files from a folder, indexes them, and gives you a search box, backlinks (links from one note to another), a graph view, and a tag system. You point it at a folder, and three minutes later, your existing mess of markdown is a searchable wiki. I have been running it for three months, and I have not lost a note since.

What SiYuan actually is

SiYuan is a single Go binary that bundles a web server, a database, and a desktop client. The free version is fully featured, with no nag screens, no per-user fees, and no telemetry. The paid version adds cloud sync and a few enterprise features, but for a personal knowledge base, the free version is enough.

The setup is genuinely short. You have three options:

• Download the desktop app (a wrapped Electron app that launches a local browser)
• Run the Docker image (a pre-packaged container with everything inside) with one command
• Build the Go binary yourself from source

I run the Docker image, because I already have a small home server. The container takes about 200 MB of RAM and starts in under five seconds.

docker run -d \
  --name siyuan \
  -v /path/to/notes:/siyuan/workspace \
  -p 6806:6806 \
  b3log/siyuan

Once it is running, you open http://your-server:6806 in a browser, set a password, and you are in. The first sync takes a minute or two, depending on how many files you have. After that, every file in the folder is indexed and searchable.

How SiYuan handles existing markdown

This is the part I was most skeptical about, and the part that surprised me the most. SiYuan does not require any specific markdown dialect. It reads CommonMark (a standardized version of markdown) and a handful of GFM extensions (GitHub Flavored Markdown, which adds tables, task lists, and autolinks) by default. It does not rewrite your files. It indexes them in its own database and leaves the source files untouched.

When you make a change in the SiYuan editor, the change is written back to the original file. When you edit a file in another tool (VS Code, vim, whatever), SiYuan picks up the change on the next sync. There is no lock-in. If you stop using SiYuan tomorrow, your files are still your files, in plain markdown, where you left them. The trade-offs that come with this design are worth knowing about:

• No proprietary format, no binary blobs, no SQLite-only exports
• Edits from outside the editor are picked up on the next sync (a few seconds)
• Folder structure is preserved; SiYuan does not reorganize your files
• Plugin behavior is contained to the database, never the filesystem

Backlinks are the killer feature here. If you write [[note-name]] or use a wiki-style link, SiYuan automatically tracks which notes link to which. Open any note, scroll to the bottom, and you see a list of every other note that references it. This is the feature that turned my flat folder of files into a connected web of knowledge. I have discovered connections between notes I wrote three years apart, just because they both happened to mention the same project.

Search is fast. With 400 files indexed, a query for kubernetes networking returns results in under 200 milliseconds. Full-text search includes the contents of code blocks, which is a feature I did not know I wanted.

The features that earned their place

A few details made the tool stick for me. Block-level structure comes first. SiYuan treats every paragraph, list, and code block as an addressable block with its own ID. You can link to a specific block in another note, and the link stays valid even if you move the block. This is the same idea as Notion’s block system, but in markdown. It is the right abstraction for a personal knowledge base.

Daily notes are the second feature. Open the app, and there is a calendar view with a button to create a note for today. Daily notes are a journal pattern: you write a quick note every day, and over time, the daily notes become a record of what you were thinking about. SiYuan makes this friction-free, and the daily note shows up in the search results alongside your longer-form notes.

Export options round out the trio. You can export any note or the entire database as a zip of markdown files. I run a weekly export to a separate backup drive. If my home server dies tomorrow, I lose nothing.

Mobile experience is solid too. The web UI is responsive and works well on a phone. I do not write long notes on my phone, but I do read them, and the experience is fine.

Trade-offs and what I do not like

No tool is perfect, and the trade-offs here are real. The learning curve is the first hurdle. SiYuan is a power tool. The default UI is dense, and there are keyboard shortcuts for almost everything. The first hour with the app is overwhelming. The second hour is better. By the third hour, the shortcuts are muscle memory.

The editor is the second limitation. SiYuan’s editor is a block-based WYSIWYG (what-you-see-is-what-you-get: a style of editor that shows formatted text as you type) with a slash menu, similar to Notion. It works well for writing, but it is not the same as writing in vim or VS Code with a markdown preview. If you prefer to write in a plain text editor and preview the result, SiYuan is not the right tool.

Sync is the third gap. SiYuan does not have built-in cloud sync. If you want to access your notes from a phone on the road, you have to either expose the port over the internet (with a reverse proxy and a domain), use a VPN, or set up Tailscale. I use Tailscale, and it works, but it is an extra step. The paid version adds cloud sync, but the free version does not.

Plugin support is the final gap. Compared to Obsidian, which has hundreds of community plugins, SiYuan has a small set of official plugins and a few community ones. If your note-taking workflow depends on a specific plugin, check the list before committing.

When SiYuan is the right tool

SiYuan is the right tool if you have an existing collection of markdown files you want to make searchable. It is the right tool if you want a local-first, self-hosted note app with no telemetry. It is the right tool if you care about block-level structure and backlinks, and you do not want to learn a new markdown dialect.

It is the wrong tool if you are not technical. The setup requires either running a Docker container or installing a desktop app, and the initial configuration is not as smooth as Notion. It is the wrong tool if you need real-time collaboration with other people. It is the wrong tool if you want a polished, consumer-grade mobile app.

The honest summary is this: SiYuan is a power tool for a power user. If you have been using markdown for years and want to add search and backlinks without rewriting your workflow, give it a try. It might be the note app you have been waiting for.