MkDocs：用 Markdown 写文档，一键生成项目站点

mkdocs 在 GitHub 上已经拿到 22,130 Star 了。

这个项目做的事情很直接：把 Markdown 文件变成一套完整的静态文档网站。配置文件只有一个 YAML，写完就能部署。

1、它是干嘛的

一句话：用 Markdown 写文档，自动生成静态网站。

写代码的人都有这种经历。项目写到一半该写文档了，直接扔个 README.md 太简陋；搭个文档站又要搞前端框架、配路由、调样式，折腾半天文档一个字没写。

MkDocs 的思路很明确：你只管用 Markdown 写内容，建站的事它来处理。写完文档执行 mkdocs build，输出一个完整的静态 HTML 目录，丢到任何能托管静态文件的地方就行。

2、为什么选它

同类工具不少。MkDocs 的优势在哪。

快。 用 Python 写的，构建几百页文档也就几秒钟。对比某些 Node.js 生态的静态站点工具，依赖装半天、构建跑半天，MkDocs 轻多了。

简单。 只有一个 YAML 配置文件 mkdocs.yml。设好站点名称、导航结构、主题选项，其他全交给默认行为。想自定义也行，加插件、换主题、写扩展都支持，但基础用法不需要碰这些。

生态成熟。 项目从 2014 年就有了，一直维护到现在。内置两个主题（mkdocs 和 readthedocs），第三方主题还有上百个。Material for MkDocs 这个第三方主题尤其流行，几乎成了技术文档站的事实标配。

Markdown 扩展丰富。 原生支持代码高亮、表格、目录、脚注、Admonition 提示框。装了 PyMdown 扩展之后还能用数学公式、任务列表、键盘按键标记这类效果。

3、安装和用法

安装：

pip install mkdocs

创建一个新项目：

mkdocs new my-project
cd my-project

这个命令会生成 mkdocs.yml 配置文件和 docs/ 目录，里面有一个 index.md 作为首页。

写文档就是往 docs/ 目录里加 .md 文件，然后在 mkdocs.yml 里配好导航：

site_name: 我的项目文档
nav:
  - 首页: index.md
  - 快速开始: getting-started.md
  - API 参考: api-reference.md

本地预览：

mkdocs serve

浏览器打开 http://127.0.0.1:8000，改文档自动刷新。写完执行 mkdocs build 生成 site/ 目录，把里面的文件推到静态托管服务就完事了。

想换 Material for MkDocs 主题：

pip install mkdocs-material

然后在 mkdocs.yml 里设 theme: material。

4、适合哪些人

MkDocs 是给写代码的人用的文档工具。如果你习惯用 Markdown 记笔记、写 README，那它几乎没有学习成本。

特别适合这几类场景：

• 开源项目的技术文档站。Python 生态里大把项目在用，Requests、FastAPI、Pydantic 的文档站都是 MkDocs 驱动的。
• 团队内部知识库。文档源文件是纯 Markdown，放在 Git 里就能做版本管理和协作评审。
• API 参考文档。配合插件可以从代码注释自动生成文档，不用手工维护两套内容。

不适合的场景也很明显：你要的是博客或者公司官网，有复杂的页面布局和交互，那 Hugo、VitePress 这类更合适。MkDocs 专注做一件事，就是项目文档站。

不适合的场景也很明显：你要的是博客或者公司官网，有复杂的页面布局和交互，那 Hugo、VitePress 这类更合适。MkDocs 专注做一件事，就是项目文档站。