极简智库 MiniDocs，Apache-2.0 开源。 它不想再做一个笔记软件，只想解决一件很具体的事：手里已经有一堆 Markdown 了，怎么让它体面地给别人读。
一、起点：文档都在，但没人读得下去
团队文档、教程手册、开源项目里的 docs/、自己攒了几年的笔记……大概率都是一堆 .md 文件，安安静静躺在某个仓库或文件夹里。
想让别人读，常见的几条路都不太顺：
- 静态站点生成器：写得挺好，但改一个错别字要重新构建、发版；非技术同事想补一段说明，得先学会提 PR。权限、访问口令、阅读统计这些，全得自己再造一遍轮子。
- 现成的文档 SaaS：开箱即用，但数据在别人的服务器上，按人头收费，读者往往还得先注册个账号。
- 干脆把仓库丢过去：对熟悉 Git 的人没问题，对其他人就是一屏看不懂的目录树；手机上读体验差，图片外链哪天失效就一片裂图，想「把这一整本发给谁」也挺别扭。
缺的从来不是编辑器——Markdown 编辑器早就够用了。缺的是把一堆文件变成一个能交付的站点的那一层：目录、阅读、权限、分享，而且数据得留在自己手里。
所以有了极简智库。
二、它是什么
一句话：开源、可自托管的 Markdown 知识库平台，写作、阅读、分享、权限一条线。
| 项目 | 极简智库 MiniDocs |
| 交付形态 | 官方单镜像，前端构建产物打进 jar，一个进程、一个端口、一个数据卷 |
| 数据 | 默认 SQLite 开箱即用，生产可切 MySQL；正文就是磁盘上普通的 .md 和图片 |
| 技术栈 | Spring Boot 3.5 / Java 17 / MyBatis-Plus / Sa-Token / flexmark；Vue 3 + Vite + TypeScript + Pinia |
| 协议 | Apache-2.0 |
| 当前版本 | 1.2.18 |
| 仓库 | github.com/cosolar/min… |
| 在线演示 | docs.minims.cn |
三、不是玩具：它现在跑着 11,000 篇文档
一个自托管项目最容易被怀疑的是「示例数据很漂亮，真用起来呢」。
所以我拿它做了一个长期运行的公开实例 docs.minims.cn：截至 2026 年 11 月，32 个知识库、11,043 篇文章、31 个完全公开，内容从 Vue 官方文档到 LeetCode 题解，从深度学习教材到 AI Agent 教程。图片、目录树、章节编号、分享短链，都是在这个规模下一点点磨出来的，不是几篇 demo 文档。
需要说明的是：那个站点只是项目的一个实例。它跑在单个容器 + 一个数据卷上，你也可以把它部署到自己的机器、自己的域名，数据全在自己的磁盘里。
四、几个不那么「顺手」，但值得说清楚的设计取舍
1. 文件即数据
磁盘上一个知识库就是一个目录，里面是普通的 .md 和图片。可以用 Git 管、可以整体打包搬走、可以 grep、可以写脚本批量整理——不把正文锁进数据库。
反过来，知识库元信息（名称、可见性）、目录排序和隐藏规则放在数据库表里，而不是写回目录里：否则一次 git clean 或重新克隆，配置就没了。
2. 两套渲染器，必须对齐
管理台工作区用 bytemd 做实时预览，阅读页和分享页由后端 flexmark 渲染。同一份 Markdown 要走两条链路，BOM、表格分隔行的横线数量、标题锚点算法都得一致。
这是项目里一半 bug 的来源，所以专门用测试守着。听起来不优雅，但「编辑时看到的」和「读者看到的」必须一样，这条没得让步。
3. 权限不绕弯
读不到就返回 404（不泄露这个库是否存在），读得到但写不到才是 403；裁决只放在一处权限服务里，业务代码里不散落角色判断。审计留痕，但不记录 token 和密码。
4. 分享是一等公民
整库或单篇，一条自定义短链就能发出去，可以加访问口令、有效期、顶栏导航菜单，链接随时能撤销。站内可见性（public / org / private）和对外发布是两条正交的轴——一个库完全可以「只有成员能改」，同时「陌生人拿着链接就能读」。
对方不需要注册账号，这件事比想象中重要。
5. 图片不赌外链
Markdown 里的相对图片统一走站内资源代理，以当前文档所在目录为基准解析；以 / 开头的路径按库内根处理，越出库根的资源给一个看得见的占位，而不是静默裂图。搬运别人带大量插图的教程时，这条特别救命。
6. 单镜像交付
前端打进 jar，后端一个进程同时伺服页面和 /api/**，不需要 nginx + app 两个容器。备份就是备份 /data 这一个卷，迁移就是把目录搬走。
五、谁会需要它
- 个人：把收藏的开源教程、几年笔记整理成一个自己的图书馆，而不是一堆吃灰的链接。
- 小团队 / 工作室：内部文档、产品手册、面试题库，用多组织、角色和维护名单管起来，对外只发该发的那一条链接。
- 开源项目维护者：把仓库里的
docs/变成读者真的会看的站点，文档照旧用 Git 管。 - 内容创作者：一整套内容一个短链，读者点开就读，不用先关注、注册或回复关键词。
六、三分钟跑起来
docker run -d --name minidocs -p 9098:9098 \
-e ADMIN_PASS='换成强密码' \
-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
然后打开 http://localhost:9098，用 admin 和你设置的 ADMIN_PASS 登录。数据库、文档、封面和日志都在 /data 里。
想从源码跑（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
一个常见坑：如果环境里设了
NODE_ENV=production，npm 会跳过开发依赖，表现是「装完了却没有 vite 命令」。加上--include=dev就好。
七、开源，欢迎来用，也欢迎来提
- 仓库：github.com/cosolar/min…
- 协议：Apache-2.0，自用、改代码、放进公司内部都可以
- 在线演示：docs.minims.cn
最欢迎的反馈是这几类：两套渲染器对不齐的边界用例、不同部署形态下踩到的坑、真实内容规模下的性能问题，以及新的阅读主题包。
如果你也在为「一堆 Markdown 怎么给别人读」发愁，先跑一个容器，把自己的 docs/ 放进去试试。 觉得它帮你省了一回事，去点个 Star 就是对开源项目最实在的支持；顺手转给同样在搭文档站的朋友，也算帮它多找到一个用得上的人。
文档最怕的不是写得不好，是没人能顺利读到它。希望这个小项目，能让你少搭一次轮子。
