跪拜 Guibai
← All articles
GitHub · Architecture · Java

Self-Hosted MiniDocs Turns a Pile of Markdown into a Shareable, Readable Library

By Cosolar ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

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.

Summary

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.

Takeaways
— MiniDocs is Apache-2.0 licensed and packs the front-end build into a single jar so one process serves pages and API on one port.
— Data defaults to SQLite; production can switch to MySQL, and the actual content remains plain .md files and images on disk.
— The public instance at docs.minims.cn runs 32 knowledge bases, 11,043 articles, and 31 fully public bases as of November 2026.
— Two renderers (bytemd preview and flexmark backend) must produce identical output; the author states this alignment is the source of half the project's bugs.
— Permission rules return 404 for unreadable content and 403 for write-only attempts, with all role decisions isolated in one permission service.
— Sharing uses custom short links with optional password, expiry, and revocation, and readers do not need to register an account.
— Relative Markdown image paths are resolved through a built-in resource proxy; out-of-root paths get a visible placeholder instead of a silently broken image.
— Backup and migration are just copying the /data volume, since there is no separate nginx container.
— Quick start uses a docker run command with ADMIN_PASS and JWT_SECRET environment variables, mapping port 9098.
— Source build requires JDK 17+, Maven 3.9+, and Node.js 20+; the front end needs `npm ci --include=dev` when NODE_ENV=production is set.
Conclusions

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.

Concepts & terms
File-as-data
A design where the actual Markdown documents and images live as ordinary files on disk, while metadata such as titles, visibility, and ordering stays in a database. Files can be versioned with Git, grepped, and moved; metadata survives clean checkouts and clones.
Single-image delivery
The front-end build is baked into the Java jar, so one process serves both the static pages and the API. This eliminates the need for a separate nginx or static file container, making deployment, backup, and migration a single-volume operation.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗