跪拜 Guibai
← Back to the summary

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: 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:

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

Minimalist Think Tank: one container, one complete chain

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.

Online demo site homepage: search, statistics, and knowledge base bookshelf

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.

Reading page: left directory tree, middle content, right outline of this article

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

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=dev fixes it.

7. Open Source, Welcome to Use, Welcome to Contribute

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.