Self-Hosted MiniDocs Turns a Pile of Markdown into a Shareable, Readable Library
Teams and maintainers whose Markdown docs stay unread can deploy MiniDocs in minutes, keep files in Git, and avoid both static-site rebuild loops and SaaS account gates. The public instance at 11,000+ articles shows the pattern works beyond toy demos, making self-hosted documentation a realistic option for production.
Static site generators force a rebuild for every typo fix, SaaS docs sit on someone else's server and demand accounts, and raw repositories intimidate non-Git users. MiniDocs takes the middle path: keep the Markdown as plain files on disk, but add a self-hosted layer that turns them into a site with a table of contents, reading view, permissions, and shareable links.
The project makes several deliberate trade-offs. Content stays in ordinary .md files and images so you can still use Git, grep, and scripts; metadata like visibility and ordering lives in a database so a `git clean` won't wipe config. Two renderers—bytemd for the editing preview and flexmark for the reading page—must produce identical output, and the author admits half the bugs come from that alignment, so tests guard it. Permissions return 404 for unreadable content and 403 for write-only, sharing works as a first-class citizen with short links and passwords, and an image proxy resolves relative paths to prevent broken images.
A public instance at docs.minims.cn already hosts 32 knowledge bases and 11,043 articles with 31 fully public, proving the setup holds at real scale. Deployment is a single container that serves both the front end and the API on one port, with all data in one volume. Quick start takes three minutes with a docker run command.
The file-as-data design is a pragmatic middle ground: it preserves Git history and grep-ability, but pushes metadata into a database so a fresh clone does not lose configuration.
Two-renderer alignment is a classic hidden cost of any split preview/read architecture; the admission that half the bugs come from it is a realistic estimate of that overhead.
Returning 404 for unreadable content instead of 403 is a simple but effective privacy measure that prevents leaking the existence of a knowledge base.
The single-image delivery model removes the need for a separate front-end server, which simplifies backups and makes migration just a directory move.