MkDocs是什么？

zhongfangxiong

下面我按**“你现在的认知起点”来解释，不假设你知道 MkDocs，也不站在“工具爱好者”的角度，而是站在一个要管理 500+ 仓库、异地团队、AI 高频产出**的技术负责人的视角。

一、MkDocs 是什么？一句话先给你结论

MkDocs = 把 Markdown 目录，自动变成“可搜索、可导航、可长期维护”的文档网站的引擎。

它不是用来“写文档”的，而是用来：

把你已经写好的 Markdown，组织、发布、持续演进。

MkDocs 不解决什么

不负责写 Markdown（AI / 人写）
不负责讨论（NodeBB 才是）
不负责权限（GitLab / Pages / 反向代理）

MkDocs 专门解决什么

Markdown → 结构化网站
统一目录、侧边栏、全文搜索
多人协作、版本可追溯
自动发布（CI 驱动）

二、MkDocs 在你这个场景里的“真实角色”

你现在的问题是：

AI 每天生成大量 md
团队不在一个城市
项目 500+
不能让大家“翻帖子考古”

在这个体系里：

组件	角色
Markdown	原材料（AI 产出）
GitLab	单一事实源（谁改了什么）
MkDocs	把“散乱 md”变成“可用知识库”
GitLab Pages	稳定发布
NodeBB	通知 + 讨论

MkDocs 是“知识仓库引擎”，不是“交流工具”。

三、MkDocs 到底长什么样（不用你想象）

MkDocs 生成的是一个典型的技术文档站：

左侧：目录树（按你定义）
右侧：正文（Markdown 渲染）
顶部：搜索框（全文搜索）
URL 稳定、可引用、可长期保存

这类站点的特点是：

3 个月后还能看懂
1 年后链接还有效
新人能顺着目录自学
AI 写的文档不会“沉没”

这正是论坛/聊天工具永远做不好的事情。

四、MkDocs 的工作方式（你会秒懂）

1️⃣ 你只关心这个目录

docs/
  index.md
  now/
    README.md
  daily/
    2026-01-05.md
  decisions/
    adr-0001-auth.md

2️⃣ MkDocs 只做一件事

读取 docs/ → 生成一个静态网站

3️⃣ 唯一的“配置文件”：`mkdocs.yml`

site_name: 团队知识库
nav:
  - 首页: index.md
  - 我在做什么: now/README.md
  - 日报:
      - 2026-01-05: daily/2026-01-05.md
  - 架构决策: decisions/
theme:
  name: material

你改的不是网页，而是目录结构。

五、为什么不用 NodeBB 直接发帖？这是关键问题

你这个问题问得非常好，而且80% 的团队一开始都会走错这一步。

NodeBB 发帖，看起来很“直接”，但在你规模下会出灾难

我直接给你对比结论：

1️⃣ 信息“寿命”完全不同

维度	NodeBB 帖子	MkDocs 文档
可见期	3～7 天	3～5 年
查找方式	搜索关键词	目录 + 搜索
链接稳定性	易被淹没	永久链接
结构化		强

论坛适合“现在讨论什么”，不适合“我们最终决定了什么”。

2️⃣ 500 项目 + NodeBB = 考古现场

你可以想象一下半年后：

“那个关于 AuthServer 改造的帖子在哪？”
“好像在 NodeBB？还是微信群？”
“是哪个版本的决策？”

而 MkDocs 的模式是：

架构决策
 ├─ adr-0001-auth-server.md
 ├─ adr-0002-oidc-nodebb.md

不是靠记忆，是靠路径。

3️⃣ NodeBB 不适合“版本演进”

你是 .NET / ABP / 基础设施重构型团队：

v1 决策
v2 推翻
v3 新方案

NodeBB 的时间线是线性的，而文档是演进式的。

MkDocs + Git 的优势是：

diff 看变更
commit 说明为什么变
旧决策可追溯

4️⃣ AI 产出在 NodeBB 会“失控”

AI 非常擅长：

写长文
写方案
写对比

但论坛：

没有审阅门槛
没有目录约束
没有生命周期管理

结果一定是：

信息爆炸 → 噪音淹没 → 再也没人看

MkDocs 强迫你做一件事：

“这个文档，应该放在哪个位置？”

这是好事，不是负担。

六、那 NodeBB 该怎么用？（正确姿势）

不是不用 NodeBB，而是只让它做它擅长的事：

NodeBB = “广播 + 讨论入口”

发布策略建议：

NodeBB 帖子永远只做一件事：
告诉大家：“有新内容/新决策/新文档了，在这里”

帖子结构固定化：

标题：📌 架构决策更新：统一 OIDC 登录方案

正文：
- 背景：多系统登录混乱
- 结论：统一走 id.loda.net
- 影响范围：NodeBB / ERP / Admin
- 文档地址：https://docs.xxx.com/decisions/adr-0003-oidc.html

👇 讨论放在本帖

讨论在 NodeBB，结论在 MkDocs。

七、这套模式在“异地 + 高频 AI + 大规模仓库”下为什么稳定

你现在的情况非常典型：

AI 写得快
人分散
项目爆炸
历史包袱重

MkDocs 给你的不是“更好看的文档”，而是：

强制沉淀（不写就不存在）
低摩擦协作（Markdown + Git）
可审计演进（谁、何时、为何）
新人可自学（不依赖你反复解释）

而 NodeBB：

负责“告诉大家发生了什么”
负责“大家怎么看”

八、一句话总结给你

NodeBB 是“现在聊什么”，MkDocs 是“我们最终怎么做”。
没有 MkDocs，你的 AI 产出一定会在 3 个月内失效。

下一步我建议你做什么（非常具体）

先 不管 500 个项目
只用 MkDocs 管三类内容：
- now/（你在干什么）
- daily/（你每天产出的 AI 结果）
- decisions/（你真正拍板的事情）
NodeBB 只发“变更通知帖 + 链接”

如果你愿意，下一步我可以直接给你一份：

极简 mkdocs.yml（你不需要理解）
3 个模板 md（now / daily / adr）
一个 CI：push → Pages 自动更新 → NodeBB/企业微信通知

你只需要照着填内容，不需要“学 MkDocs”。

乐达