跪拜 Guibai
← Back to the summary

MiniDocs: A Self-Hosted Knowledge Base That Makes Sharing a First-Class Feature

MiniDocs: The Perfect Replacement for docsify, VitePress, Notion and Other Knowledge Base Services

First, a small thing that bothered me many times

I want to send a technical document to someone.

The person is not on my team; they don't need collaboration, comments, or a long-term presence in my system. They just want to read a few pages and leave.

But to get those few pages, the typical flow looks like this:

That's the "too heavy" tier: the document is mine, but the barrier is on the other party.

What about static documentation sites? I'm familiar with docsify and VitePress, and writing is fairly convenient. But they are purely static outputs: adding a document requires a commit, a rebuild, and a deployment; there are no permissions, no multi-person maintenance, no access statistics, and no way to temporarily give a client a password-protected link. To fix a typo in the body, you have to go through the entire release process.

That's the "too crude" tier: the cost of changing an article is higher than writing one.

One end is too heavy, the other too crude. The middle tier — writing as smooth as a CMS, sharing as light as sending a link, and data still held in your own hands — seems to have always been missing.

So I wrote one myself: MiniDocs.

In one sentence: writing in the backend, reading in the link, data on your own server.

In the title I used the word "perfect replacement," which needs a bit of explanation.

It's not that it has more features — quite the opposite, it has fewer than these others. I say "replacement" because the missing piece in these three is exactly the complementary half of each other: Notion has a great editing experience, but sharing first goes through a registration wall; docsify/VitePress are zero-dependency and light, but adding a document requires a release; and none of them truly own your data — one is on someone else's cloud, and the other, although the output is yours, is essentially just a pile of built HTML that can't be modified, managed, or tracked to see who viewed it.

MiniDocs wants to get three things at once: write like a CMS, be as fast as a static site, and belong to you like a self-hosted service.

As for "perfect," it has conditions. At the end I list the scenarios it's not suitable for, and those are more important to look at than the advantages.

3d498fe17adc6ca5eea849c8242d4fd1.png

Three things I figured out

Before starting, I wrote down what I didn't want. The knowledge base category is already crowded; any of the names mentioned above has more features and a bigger team than I do. Building "another version of someone with fewer features" made no sense.

So MiniDocs only makes trade-offs based on three judgments.

1. Sharing is a core feature, not an accessory switch

Most knowledge bases only have two sharing levels: public or not public.

But in real scenarios, I need a finer layer: who this link is for, how long it stays valid, and whether it can be revoked.

So in MiniDocs, each share is an independent object:

The recipient doesn't need to install anything or register; they can read as soon as they get the link.

2. Permissions only need four axes

Enterprise-level permission systems can have dozens of switches, but most teams can't configure them properly, and in the end all documents become "visible to everyone."

I only kept four dimensions:

Dimension Values What it controls
Library visibility public / org / private Who can see this library
Maintenance scope owner_only / members / org_all Who counts as the maintainer of this library
Member role OWNER / EDITOR / VIEWER Read / write / governance / sharing
Sharing Independent of the above three Who a link is sent to

The rules are implemented in exactly one place — permission/AccessService. Business code is not allowed to compare roles or owners itself, and static guards in tests block such code.

This "single referee" design is a limitation in the short term, but it saves lives in the long term. Six months later, you won't want to know "who exactly is deciding permissions on this interface."

3. Deployment should be doable by an ops novice

Many open-source projects end their README at docker-compose up, and then you open the browser and see a bunch of configuration errors.

MiniDocs's goal is: one container, one port, one data volume, up and running.

export ADMIN_PASS='change to a strong password'
export JWT_SECRET="$(openssl rand -base64 48 | tr -dc 'A-Za-z0-9' | head -c 48)"

cd deploy
docker compose -f docker-compose.standalone.yml up -d

Open http://server-IP:9098, the default administrator is admin / admin123 (change it immediately on first login). Data defaults to the Docker volume minidocs-data, using built-in SQLite, no need for a separate database container.

If you really want MySQL, set SPRING_PROFILES_ACTIVE to prod and add three connection parameters — the same jar, dual dialect for SQLite/MySQL, and the table creation and content migration scripts run automatically on startup.

What it can actually do

Features are listed here; you can pick based on your own scenario.

Writing

Markdown (GFM) editing with live preview is the basic baseline: tables, task lists, code block syntax highlighting, and one-click copy.

On top of that, a few things that make "writing" smoother:

What if multiple people edit the same article at once? Two safeguards: edit lock (60-second renewal, auto-yields on timeout, so articles won't be locked forever if someone leaves) plus optimistic concurrency (baseline includes size and mtime, conflicts return 412, so others' changes won't be silently overwritten).

Reading

The reading page and share page share the same rendering pipeline, so "what I see" and "what I send out" are always consistent — many products can't do this; the editor preview looks fine, but the styles break when shared.

c2ba29d25c2e7d6f02eb0f8ae0f6beae.png

Sharing

Already covered above, two more details:

aa1181af7aa5bae90443144b5b5e4f1e.png

Organization and governance

Registration page: email is identity, username is auto-generated, and after registration you have your own organization

A few technical decisions I'm quite satisfied with

If you're also a backend developer, this section might be more interesting than the feature list.

One render, two reuse. The render cache key is kbId + path + mtime + size, and the portal view and share view reuse the same HTML. It's not two templates rendering separately; it's the same output with two entry points.

Zero external dependency for full-text search. No Elasticsearch, no Lucene; it's just an in-memory inverted index, with an upper limit of about 2,000 articles, and hits directly give the title link. For the scale of "personal blog / small team," one more middleware is one more source of operational incidents.

Admin panel lazy-loaded. Element Plus is only dynamically loaded when entering /console/**, /login, or /platform/**. The portal and reading pages don't include the component library in their output, so the first screen is very light — the reading page is the most frequently accessed part of a knowledge base, and it shouldn't pay the price for table components in the backend.

Security defaults are tightened. Strict CSP and security response headers; share cookies are HMAC-signed and scoped to the root; unauthorized access is always 404. These are not features added at the end; they are constraints present from the first version.

Tech stack: backend Spring Boot 3 + MyBatis-Plus + Druid + Sa-Token + flexmark, frontend Vue 3 + Vite + Pinia, single SPA built once.

Get it running in three minutes

Quickest path: look at the online version. https://docs.minims.cn

The demo site currently hosts 6 knowledge bases and 243 documents — "Hands-on Large Models," "AI Agent Handbook," "Deep Understanding of AI Agents," "Technical Interview Notes," "Minimal Resume Document Center," and so on. These are not fake articles filled with padding; they are content I actually maintain. You can register an account, or not register at all and just view the shared libraries.

Demo homepage: 6 knowledge bases, 243 documents, 1,135 visits, all real content

Local run: Requires JDK 17+, Maven 3.9+, Node.js 20+.

cd front && npm install && npm run build
cd ../backend && mvn spring-boot:run

Open http://localhost:9098. In the dev profile, SQLite is used out of the box; no database configuration needed.

Small pitfall in advance: if the environment variable NODE_ENV=production, npm install will skip devDependencies, so when installing dependencies you must explicitly include --include=dev.

Production: Use the Docker command above; for front-end/back-end separation, give the front-end build to any static server, and the back-end only provides APIs. Nginx only needs two sections — one try_files for SPA deep-link fallback, and one reverse proxy for /minidocs/ to the backend. Full configuration, systemd, backup/upgrade, and troubleshooting are in the deployment guide.

Who it's not for

The "perfect replacement" in the title needs a discount here.

It's not a replacement for every scenario. In the following cases, I recommend you stick with your original solution and don't bother:

If you want an integrated office suite combining "team collaboration + instant messaging + calendar + approval," use Feishu or DingTalk; MiniDocs doesn't solve that.

If you want a "purely static, zero-backend, push to GitHub Pages" documentation site, docsify or VitePress are lighter; you don't need a database.

If your document volume is in the hundreds of thousands and you need complex search ranking and aggregation analysis, you should go with Elasticsearch; MiniDocs's in-memory index will hit its limit first.

If your team needs paragraph-level comments, @mentions, and approval flows, the current version doesn't have them.

Conversely, as long as your scenario fits in this sentence, it can probably replace your current setup: you maintain a batch of Markdown documents, need to organize them structurally (multiple libraries, tree directories, tags), need permission boundaries within the team, and need to cleanly share certain parts externally.

Personal bloggers, small studios, technical teams, and open-source project document centers — these are the people I had in mind when designing it.

Current status

The project was open-sourced at the end of September, current version v1.2.11, Apache-2.0, usable commercially.

To be blunt, it's still young. Over a month, the code has been written line by line by a single person, and I've patched many rough edges by stepping on the traps myself. This means two things:

First, don't expect it to have everything. If a feature is missing, you can open an issue and I'll likely respond.

Second, feedback right now is most useful. By the time it grows to 10,000 stars, your words won't be as useful as they are now — all open-source authors say this, but it's true.

If you think this thing is somewhat useful:

If you just want to see how others use it: the libraries on the demo site are real live content, feel free to browse.

Link summary