LeafWiki: a single Go binary that keeps your Markdown on disk

The operational weight LeafWiki is trying to remove

The problem here is not documentation. It is the cost of running the thing that holds the documentation. A wiki that needs Node.js at runtime, a Redis instance for sessions, and a Postgres server for content turns a two-person team's runbook collection into a service with a dependency graph. LeafWiki's README states the target directly: no Node.js, no Redis, no Postgres, just a binary and a data directory. The stated audience is engineers and self-hosters who want structured, long-lived documentation, and the README names the moment of comparison explicitly, addressing anyone who looked at Wiki.js or Outline and concluded it was too much to operate for the need at hand. That is a narrower claim than it first appears. LeafWiki is not competing on features. It is competing on the number of things that can break at 3am. The README also lists who should walk away: organizations needing complex enterprise permissions or approval workflows, teams wanting real-time collaborative editing, and anyone shopping for a Confluence or Notion replacement. A project that publishes its own non-fit list is telling you where its boundary is, and this one draws that boundary close in.

Markdown files on disk, SQLite for the rest

The storage split is the core design decision. Page content lives as Markdown files on the filesystem, and the README describes the consequence plainly: page content is readable outside the app, and backup is cp -r with the caveat that you stop the app first. SQLite carries the structured data around those files, which by implication covers users, roles, search indexing, tags, backlinks and sort order. That split explains several features at once. Full-text search across titles and content exists as a database concern rather than a grep over the directory, because SQLite indexes it. Tags are searchable and filterable for the same reason. Manual page ordering is possible because sort order is stored as data, not derived from filenames, which the README calls out as a deliberate difference from filename-driven ordering. The architecture also produces a documented failure surface: because files can be edited outside the application, there is a resync path for external edits, and the README devotes a section to it. That section exists precisely because the on-disk format is a public interface. You can edit a file in your editor of choice, but the application needs to be told the file changed. The same property is what makes the backup story credible, and it is the same property that makes concurrent out-of-band edits something to think about.

Getting a container running and the flags that matter

The README's first command is a docker run with three flags and a volume: docker run -p 8080:8080 -v ~/leafwiki-data:/app/data ghcr.io/perber/leafwiki:latest --jwt-secret=yoursecret --admin-password=yourpassword --allow-insecure=true. The --allow-insecure flag is required for plain HTTP and should be omitted when serving over HTTPS, provided the reverse proxy forwards X-Forwarded-Proto: https. A non-root variant adds -u 1000:1000, and the README notes the data directory must be writable by that user. Docker Compose maps the same three settings to environment variables: LEAFWIKI_JWT_SECRET, LEAFWIKI_ADMIN_PASSWORD and LEAFWIKI_ALLOW_INSECURE. Beyond install, the flags that change behaviour are worth reading before you deploy. Three access modes are documented: fully internal, public read with login-only editing, and open editing without login. Roles are admin, editor and viewer. Several capabilities are opt-in rather than default, including revision history via --enable-revision and automatic link rewriting on rename or move via --enable-link-refactor. SMTP for password reset and invitations arrived in v0.13.0 through --smtp-host. Git backup, added in v0.11.3, is marked experimental in the README. Reverse-proxy authentication via a trusted HTTP header has been available since v0.10, and a Unix socket option since v0.11.3. The pattern is that the default install is minimal and you add surface area deliberately.

Revision history and link refactoring are off by default

This is the design choice most likely to surprise someone migrating from a heavier wiki. Revision history does not exist unless you pass --enable-revision. Link rewriting when a page is renamed or moved does not happen unless you pass --enable-link-refactor. Both defaults are defensible for a single-binary tool that wants a small footprint, but they change what the product is. Without revision history, an overwritten page is gone unless you have filesystem snapshots or the Git backup running. Without link refactoring, moving a page in the tree leaves broken links behind. LeafWiki does mitigate that second case: it tracks link status per page, covering incoming, outgoing and broken links, and provides a dedicated admin view for auditing broken links. So the project's position is that you can find the damage rather than that you can prevent it, unless you opt in. The README also documents a snapshot restore path that is explicitly offline. Anyone treating LeafWiki as a system of record should decide about both flags before the first page is written, because turning revision history on later does not retroactively create history for pages already saved. The README does not state whether enabling the flag backfills anything, so assume it does not and verify on a copy.

Where LeafWiki is the wrong tool

The README's own not-a-fit list is the honest starting point, and it is worth taking at face value rather than as modesty. No real-time collaborative editing means two people editing the same page are not co-editing; the README instead cites optimistic locking for concurrent edits, which detects a conflict rather than merging one. No approval workflows and no complex enterprise permissions means the access model is three roles and three operating modes, full stop. The Markdown importer is another boundary. It is ZIP-based, available to editors and admins, and supports Obsidian-style wiki link rewriting on import, but the README warns it is not a fully automatic converter for all source formats and works best with a reasonably clean folder structure. If your existing documentation is a decade of nested Confluence export directories with macros and attachments, the importer is not going to rescue it. There is also a feature to be skeptical of: API keys for programmatic and agent access are described as admin-managed, read-only, and in development, not yet ready for use. Treat that as absent. Finally, the README states that backup is cp -r with the app stopped, which means no live hot backup path is documented. For a personal wiki that is fine. For a team where the wiki is the only place a procedure exists, stopping the service to take a consistent copy is a real constraint.

How this differs from Wiki.js and Outline

The README positions LeafWiki against Wiki.js and Outline, so the comparison is fair game, with the caveat that only LeafWiki's side is documented here. The difference is architectural rather than feature-level. Those systems are typically deployed as an application server plus a database server, which is what makes them capable of fine-grained permissions, rich plugin ecosystems and multi-user workflows, and also what makes them something you operate. LeafWiki collapses the application into one Go binary and the content into files, accepting a smaller feature set in exchange. The consequence you feel day to day is in the backup and inspection story. With LeafWiki, the README's claim is that page content is readable outside the app, so you can open a page in any editor, diff it, and put it under version control independently of the wiki. With a database-backed wiki, content is inside the database and your access to it runs through the application or a SQL client. That is a genuine difference in who owns the bytes. It is also why LeafWiki's opt-in Git backup exists: if your content is already files, pushing it to a remote repository is a small step, and the README describes that feature as pushing wiki content to a remote Git repository over SSH or HTTP(S).

Maintenance cadence and what the MIT licence leaves you

The release history shows a steady cadence: v0.13.0 on 2026-09-08, v0.12.1 on 2026-08-16, v0.12.0 on 2026-07-26, with the repository last pushed 2026-09-10 and not archived. Roughly a release a month over that window, and the version numbers still sit below 1.0, which matters when you are deciding whether to build a workflow on top of a specific flag. Several capabilities are explicitly gated by version in the README: custom stylesheet at v0.8.5, reverse-proxy authentication at v0.10, Unix socket and Git backup at v0.11.3, SMTP at v0.13.0. If you pin an older image, those flags are not there. The upgrade cost is low on paper because the artefact is a container image and the data is a directory, but the on-disk Markdown format is an interface, and the resync section exists because external edits are expected. Any upgrade that changes how pages are represented on disk has a migration implication for content you have edited by hand. The MIT licence is permissive: it allows commercial use, modification and redistribution with the licence and copyright notice preserved. It provides no warranty, and this is not legal advice. If you embed LeafWiki in something you ship, the practical question is not the licence text but whether you are prepared to maintain a fork, since there is no commercial support tier described in the material.

Who this is for, and what to check before you commit

The clearest fit is a homelab or small engineering team that already keeps notes in Markdown, wants a tree rather than a feed, and would rather not run a database server to get it. The README's good-fit list names personal wikis, engineering notebooks, runbooks, internal team documentation, and existing Markdown or Obsidian vaults that need a structured UI. The clearest non-fit is any organization whose requirements include approval chains or per-space permissions, because those are not in the model. Between those poles, the deciding question is whether you need revision history, and the answer determines your deployment before you write a page. Turn on --enable-revision and --enable-link-refactor at install time, or accept that renames produce broken links you will find through the admin link audit view rather than prevent. There is a hosted beta mentioned in the README with ten spots starting September 2026 and a waitlist, but the self-hosted path is the documented one. The project also asks for translations, shipping English, German and Spanish with --default-language selecting the default and docs/i18n.md describing the process. If your team works in a fourth language, that is a contribution you would be making, not a feature you would be configuring.

Editorial conclusion

Adopt LeafWiki if you want a tree-structured wiki whose page content you can read with cat and back up with cp -r, and if you accept that permissions stop at admin, editor and viewer. Do not adopt it if you need real-time collaborative editing, approval workflows, or enterprise permission models, all of which the README lists as out of scope. Before committing, verify three things yourself: that the ZIP importer handles your existing vault structure, that --enable-revision and --enable-link-refactor behave as you expect on a copy of your data, and that the Git backup feature, which the README labels experimental, completes a push to your remote. Note also that API keys are described as in development and not yet ready for use, so any programmatic access plan should be treated as unproven.

Official sources

1. License: MIT
2. perber/leafwiki on GitHub
3. Project website
4. README
5. Releases