Self-Hosted MiniDocs Turns a Pile of Markdown into a Shareable, Readable Library
Minimalist Think Tank: Turn Markdown into Your Own Knowledge Base
Minimalist Think Tank MiniDocs, open-sourced under Apache-2.0. It does not want to be another note-taking app; it only wants to solve one specific problem: you already have a pile of Markdown files, how do you get them read gracefully by others?
1. The Starting Point: The Docs Are There, But Nobody Reads Them
Team documentation, tutorial manuals, docs/ folders in open-source projects, years of personal notes... they are all likely a bunch of .md files sitting quietly in some repository or folder.
When you want others to read them, the common paths are all a bit awkward:
- Static site generators: They write well, but fixing a typo requires a rebuild and a release; a non-technical colleague who wants to add a paragraph must first learn how to submit a PR. Permissions, access tokens, reading statistics—you have to reinvent all these wheels yourself.
- Ready-made documentation SaaS: Easy to get started, but your data lives on someone else's server, it charges per user, and readers often need to register an account first.
- Just toss the repository over: This works fine for people familiar with Git, but for everyone else it's a screen full of an incomprehensible directory tree; the mobile reading experience is poor, external image links can break anytime leaving broken images, and "sending this whole book to someone" is also awkward.
What's missing is never an editor—Markdown editors have long been sufficient. What's missing is the layer that turns a bunch of files into a deliverable site: table of contents, reading, permissions, sharing, and the data must stay in your own hands.
So Minimalist Think Tank came into being.
2. What It Is
In one sentence: an open-source, self-hostable Markdown knowledge base platform that brings together writing, reading, sharing, and permissions in one line.
| Project | Minimalist Think Tank MiniDocs |
| Delivery form | Official single image; front-end build bundled into a jar; one process, one port, one data volume |
| Data | Default SQLite works out of the box; production can switch to MySQL; the content itself is ordinary .md files and images on disk |
| Tech stack | Spring Boot 3.5 / Java 17 / MyBatis-Plus / Sa-Token / flexmark; Vue 3 + Vite + TypeScript + Pinia |
| License | Apache-2.0 |
| Current version | 1.2.18 |
| Repository | github.com/cosolar/minidocs |
| Online demo | docs.minims.cn |
3. Not a Toy: It's Currently Running 11,000 Documents
The most common suspicion about a self-hosted project is "the sample data looks pretty, but what about real usage?"
So I ran a long-term public instance docs.minims.cn with it: as of November 2026, 32 knowledge bases, 11,043 articles, 31 fully public, covering everything from the Vue official docs to LeetCode solutions, from deep learning textbooks to AI Agent tutorials. Images, directory trees, chapter numbering, share short links—all were refined at this scale, not with a few demo documents.
Please note: that site is just an instance of the project. It runs on a single container plus one data volume; you can deploy it to your own machine, your own domain, and all the data stays on your own disk.
4. A Few Design Trade-offs That Are Not So "Easy", But Worth Being Clear About
1. Files as Data
A knowledge base on disk is a directory containing plain .md files and images. You can manage it with Git, package it and move it wholesale, grep it, write scripts to batch-organize it—the content is not locked into a database.
Conversely, knowledge base metadata (name, visibility), directory ordering, and hidden rules live in database tables rather than being written back into the directory; otherwise, a git clean or a fresh clone would wipe out the configuration.
2. Two Renderers Must Align
The admin workspace uses bytemd for real-time preview, while the reading page and share page are rendered by flexmark on the backend. The same Markdown must go through two pipelines—BOM, the number of dashes in table separator rows, heading anchor algorithms all have to match.
This is the source of half the project's bugs, so tests specifically guard it. It may not sound elegant, but "what you see while editing" and "what readers see" must be identical; this is non-negotiable.
3. Permissions Without Detours
If you can't read it, return 404 (don't leak whether the base exists); if you can read it but not write, return 403. The decision is concentrated in a single permission service; no scattered role checks in business code. Auditing is left traces, but tokens and passwords are not recorded.
4. Sharing Is a First-Class Citizen
Share an entire base or a single article with one custom short link, add an access password, expiry date, top navigation menu, and revoke the link at any time. In-site visibility (public / org / private) and external publication are two orthogonal axes—a base can be "only members can edit" while "strangers can read it with the link."
The other party doesn't need to register an account; that matters more than you think.
5. Images Don't Bet on External Links
Relative images in Markdown uniformly go through an in-site resource proxy, resolved against the current document's directory; paths starting with / are treated as base-root, and resources that go beyond the base root show a visible placeholder instead of silently breaking. This is especially life-saving when importing tutorials from others that have lots of images.
6. Single-Image Delivery
The front-end is bundled into the jar, and the backend process serves both pages and /api/** in one process—no need for nginx + app as two containers. Backing up is just backing up the /data volume; migration is simply moving the directory.
5. Who Would Need It
- Individuals: Organize collected open-source tutorials and years of notes into your own library, instead of a pile of dead links.
- Small teams / studios: Internal docs, product manuals, interview question banks—use multi-org, roles, and maintainer lists to manage them, and only send out the one link that should be public.
- Open-source maintainers: Turn the
docs/in your repository into a site readers will actually look at, while still managing docs with Git. - Content creators: One short link for a whole set of content; readers click and read, no need to follow, register, or reply with a keyword.
6. Run in Three Minutes
docker run -d --name minidocs -p 9098:9098 \
-e ADMIN_PASS='replace with a strong password' \
-e JWT_SECRET="$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 48)" \
-v minidocs-data:/data \
minimscn/minidocs:1.2.18
Then open http://localhost:9098, log in with admin and the ADMIN_PASS you set. The database, documents, covers, and logs all live in /data.
To run from source (JDK 17+ / Maven 3.9+ / Node.js 20+):
git clone https://github.com/cosolar/minidocs.git
cd minidocs/front && npm ci --include=dev && npm run build
cd ../backend && mvn spring-boot:run
A common pitfall: if your environment has
NODE_ENV=production, npm will skip dev dependencies, resulting in "installed but no vite command". Adding--include=devfixes it.
7. Open Source, Welcome to Use, Welcome to Contribute
- Repository: github.com/cosolar/minidocs
- License: Apache-2.0, fine for personal use, editing code, or putting it inside a company
- Online demo: docs.minims.cn
The most welcome feedback falls into these categories: edge cases where the two renderers fail to align, pitfalls under different deployment shapes, performance issues at real content scale, and new reading theme packages.
If you're also agonizing over "how do I get a pile of Markdown read by others," run a container first and drop your docs/ in to try it. If it saves you a round, starring it is the most practical support for an open-source project; passing it along to friends who are also building doc sites counts as helping it find another person who can use it.
The worst thing for documentation is not that it's poorly written, but that no one can read it smoothly. I hope this small project lets you avoid rebuilding the wheel one more time.