MkDocs 项目文档站点搭建：pip 安装、本地预览与 YAML 配置

MkDocs 这个写项目文档的工具确实顺手，值得花几分钟掌握用法，顺便分享给有需要的同学。

什么是 MkDocs？

MkDocs（Markdown Documents）是一个快速、简单的静态网站生成器，用来把 Markdown 文档组织成层次清晰、界面美观的文档站点。

快速上手

下面从零开始用 MkDocs 搭一个站点，感受它的轻量快捷。

首先，确保已安装 Python3，然后执行 pip install mkdocs 完成安装。

这样就安装完了。想知道装到哪里，可以运行 pip show mkdocs。

然后，按下面两步新建站点：

1. 使用 mkdocs new <your-site-project-name> 新建站点项目。比如我这里叫 mysite，执行 mkdocs new mysite。
2. 进入 mysite 目录：cd mysite，然后运行 mkdocs serve 在本地启动。

第三步？没有第三步。打开浏览器访问 localhost:8000，就能预览 MkDocs 搭好的文档站点了。

cmd 里能直接敲 mkdocs 指令的原因：因为存在 mkdocs.exe 文件🧐。它位于 Python 安装目录下的 Scripts 文件夹：D:\program\Python313\Scripts。该目录已被加入系统 PATH 环境变量，因此任意目录都能执行 mkdocs new、mkdocs serve 等命令。

假如已有项目目录，也不必从头创建站点。

直接在原目录下新建一个 docs 文件夹，里面放一个 index.md；再在原目录下建一个 mkdocs.yml 文件，填入基本信息，然后运行 mkdocs serve 就能看到效果。例如：

my-exist-projct
├── docs
│   ├── index.md
│   ├── notes
│       ├── mkdocs.md
│       └── python.md
└── mkdocs.yml

多数基于 MkDocs 的文档站点，目录结构都类似：

• docs：存放所有 Markdown 文档。也可以用子目录进一步归类，这是 MkDocs 运行时的默认根路径，后续可手动修改。
• mkdocs.yml：负责 MkDocs 的定制化配置。
• docs/index.md：必须有，这是 MkDocs 构建的首页入口。

因为 MkDocs 只处理 Markdown 文件，除了把电子笔记放进 docs，还要确保扩展名为 .md。

YAML 配置文件格式速成

稍等！虽然 Markdown 文档已准备好，但要让 MkDocs 跑起来还差一步：编写配置文件。

和前面提到的其他框架一样，MkDocs 的许多可选配置都通过 mkdocs.yml 这个 YAML 文件管理。所以简单了解 YAML 很有必要。

YAML 是 “YAML Ain't Markup Language” 的递归缩略语，是一种人类可读的数据序列化语言，扩展名 .yml 或 .yaml（官方推荐）。它常被拿来像 JSON 一样编写配置或存储数据。

YAML 官方文档长达八十多页（丧心病狂），也从侧面说明其语法特性非常丰富。不过文档厚归厚，“二八定律”依然成立：80% 语法简单常用，20% 不常用，需要时再查。而 MkDocs 本身配置项不多，编写 mkdocs.yml 时真正用到的 YAML 语法可能连 10% 都不到。

所以，只要记住下面三个核心元素，就能应付大多数 YAML 配置场景：

1. 键值对（Key-Value Pair）：name: wangyue
2. 空格缩进（indent）：空格（ASCII 32）有时会与 Tab 产生的制表符（ASCII 9）混在一起，单从外观无法分辨。为避免 YAML 解析错误，应遵循官方要求使用两个半角空格缩进。
3. 同一层级下不能有重名键。

如果你也在折腾这类文档工具，欢迎到 云栈社区 和更多开发者一起交流。