AAsteriadne

website

MkDocs

所属分类：开发者在线工具箱

MkDocs：用 Markdown 与 YAML 配置生成项目文档网站的工具

代码文档

MkDocs 是一个静态网站生成器，用来为代码项目或资料项目搭建文档网站。文档源文件用 Markdown 书写，站点结构由一个 YAML 配置文件定义，最终输出可以直接部署的 HTML。

MkDocs：用 Markdown 编写项目文档并生成静态网站

发布于 2026年10月18日更新于 2026年10月29日

首页与导航结构

首页用“fast, simple and downright gorgeous”形容 MkDocs，并把读者引向“Getting Started”（入门教程）和“User Guide”（用户指南）两个入口。顶部导航中另有 Developer Guide，内容包括主题、翻译、插件和 API 参考；About 下面则是发布说明、贡献指南与许可证。页面底部的“Edit on GitHub”链接可以直接打开 GitHub 上对应页面的源文件。

MkDocs 官网首页截图：顶部为蓝色导航栏，正文标题为 MkDocs，下方是“Getting Started”和“User Guide”两个按钮，以及四张介绍主题、自定义、实时预览和部署的功能卡片

从安装到第一个文档站点

入门教程的第一步是运行 pip install mkdocs。随后执行 mkdocs new my-project 创建项目，新项目里有一个 mkdocs.yml 配置文件，以及默认存放文档源文件的 docs 文件夹，其中起始页为 index.md。进入项目目录后运行 mkdocs serve，内置开发服务器会在 http://127.0.0.1:8000/ 提供预览，修改文件后浏览器会自动刷新。教程还指出，配置文件中唯一必填的选项是 site_name。

配置与 Markdown 扩展

用户指南的配置页说明，MkDocs 使用 Python Markdown 库把 Markdown 转换为 HTML。默认启用的扩展有 meta、toc、tables 和 fenced_code；如需更多格式功能，可以在 markdown_extensions 列表中添加扩展。部分扩展还支持嵌套的选项设置，例如为目录扩展开启固定链接（permalink）。

MkDocs 用户指南配置页截图：左侧为 Configuration 章节目录，Formatting options 为高亮项，正文标题为 markdown_extensions，下方配有 YAML 示例代码

主题、插件与部署

内置主题有 mkdocs 和 readthedocs 两种。想要其他外观，可以从 MkDocs Themes 维基页和 MkDocs Catalog 中选择第三方主题，也可以自己制作主题。插件和 Markdown 扩展用于扩展功能。MkDocs 生成的是完全静态的 HTML，首页列出的托管选择包括 GitHub Pages 和 Amazon S3，也可以放在其他任何地方。