10 用 MkDocs 搭自己的文档站¶

本站（你在看的这个）就是用 MkDocs 搭的。 这一章教你把一堆 .md 变成有搜索、有侧栏、有暗色模式的正式文档站。

MkDocs 是什么¶

一个 Python 写的静态站点生成器：读 docs/ 下的 .md → 输出纯静态 HTML
配合主题 Material for MkDocs，界面现代、自带中文搜索、暗色模式
不需要服务器后端，丢任何静态托管（Nginx、GitHub Pages、Vercel）就能跑

1. 安装¶

# 建议用 Python 3.9+
pip install mkdocs mkdocs-material
# 或
pip install "mkdocs-material[all]"

mkdocs --version

2. 创建项目¶

mkdocs new my-docs
cd my-docs

生成的结构：

my-docs/
├── mkdocs.yml     # 配置文件（关键）
└── docs/
    └── index.md   # 首页

3. 本地预览¶

mkdocs serve
# 浏览器打开 http://127.0.0.1:8000

改 md 文件自动刷新，边写边看。

4. 配置 mkdocs.yml¶

一个够用的完整配置（本站 markdown-docs-src/mkdocs.yml 就是这套）：

site_name: 我的文档站
site_description: 一句话介绍
site_url: https://example.com/docs/

docs_dir: docs

theme:
  name: material
  language: zh          # 中文界面
  custom_dir: overrides # 自定义模板目录（可选）
  features:
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      primary: pink
      accent: pink
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - scheme: slate
      primary: pink
      accent: pink
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - footnotes
  - tables
  - attr_list
  - toc:
      permalink: true

nav:
  - 🏠 首页: index.md
  - 第一部分 · 入门:
      - 01 什么是 Markdown: 01-what-is-markdown.md
      - 02 编辑器与预览工具: 02-editors-tools.md
  - 附录:
      - 📋 速查表: 12-cheatsheet.md

几个要点

配置	作用
`language: zh`	界面、搜索按钮变中文
`palette` 两组	亮色/暗色切换按钮
`pymdownx.tasklist`	让 `- [x]` 复选框显示出来
`pymdownx.superfences`	代码高亮 + 支持嵌套代码块
`tables`	表格（不启用则表格不渲染）
`toc: permalink`	标题旁生成可复制的锚点
`nav`	决定侧栏结构与顺序（顺序按这里来，不按文件名）

⚠️ nav 里列出的文件必须在 docs/ 里真实存在，否则构建报错。

5. 构建¶

mkdocs build -d /www/wwwroot/mysite/docs
# 或直接 mkdocs build（默认输出到 site/）

产物是纯静态文件，Nginx 指向该目录即可：

server {
    server_name docs.example.com;
    root /www/wwwroot/mysite/docs;
    index index.html;
    location / { try_files $uri $uri/ =404; }
}

6. 常用扩展语法¶

Material 主题下多了这些好用的写法：

!!! note "提示标题"
    提示内容，缩进四个空格。

!!! warning "警告"
    这是警告框。

??? tip "可折叠"
    默认收起，点击展开。

=== "标签一"
    内容一

=== "标签二"
    内容二

得到的效果就是本站里那些彩色提示框、折叠块、Tab 切换。

7. 给站点加「AI 问答」悬浮按钮¶

本站每个页面右下角都有 💬 按钮（/doc-ai/widget.js）。做法是在 overrides/main.html 里注入一段脚本：

{% extends "base.html" %}

{% block scripts %}
  {{ super() }}
  <script src="/doc-ai/widget.js" defer></script>
{% endblock %}

然后在 mkdocs.yml 里声明 theme.custom_dir: overrides，构建时就会用你的模板覆盖默认模板。

8. 常见问题¶

现象	原因	解决
`Config value 'nav': ... not found`	nav 里的文件不存在	文件名拼写检查
中文搜索搜不到	没装 material 或语言没设	`language: zh` + 装 `mkdocs-material`
表格/复选框不显示	缺 `tables` / `pymdownx.tasklist` 扩展	补进 `markdown_extensions`
改了配置没生效	只 build 没重启 serve	重启 `mkdocs serve`
页面 404	链接写成了 `.md` 但站点用目录形式	MkDocs 会自动转换，检查相对路径
构建很慢	文档非常多	正常，可加 `--strict` 提前发现错误

9. 本站的构建流程（真实例子）¶

# 源文件在 ~/markdown-docs-src/，构建到线上站点目录
cd /root/.openclaw/workspace/markdown-docs-src
mkdocs build -d /www/wwwroot/docx.ffsmcserver.top/markdown-docs-zh

改内容 → 重新 build → Nginx 直接生效。不需要重启任何服务。

本章练习¶

装好 mkdocs + material，mkdocs new 一个项目。
加两页内容，用 nav 分组。
mkdocs serve 预览，切一下暗色模式。
mkdocs build 出静态文件，看看产物长什么样。

下一章：GitHub README 与文档规范。