同事前两天问我项目文档散落在几个仓库的 README 和 Wiki 里每次发布新版本都要手动截图、复制粘贴、重新导出一份 PDF太折磨人了。有没有什么办法写一次 Markdown保存之后自动渲染成站点还能在每次提交代码后自动更新我直接给他甩了一套 MkDocs GitHub Actions 的方案半天时间就帮他搭完了。今天把这套东西完整拆开讲一遍包括我踩过的几个坑。1. 为什么偏偏选 MkDocs而不是其它方案先说结论如果你写的是项目文档团队知识库API 使用说明这类偏技术、偏结构化的内容MkDocs 是最省心的选择。它不追求像 VuePress 或 Docusaurus 那样的前端自定义能力它追求的就是把 Markdown 变成漂亮的文档站点这一件事。1.1 MkDocs 与 Sphinx、VuePress 的核心差异很多人一上来就纠结选型我直接给一张对比表方便你按需取用对比项MkDocsSphinxVuePress / Docusaurus定位Python 生态的 Markdown 文档生成器Python 生态偏 API 文档和科技写作Node 生态偏组件库文档和产品官网上手成本极低一条命令启动中需要理解 reStructuredText 和扩展机制中高需要懂一点 Node 和 Vue/React 概念主题生态Material 主题足够专业主题偏学术和工具风生态大但配置复杂度上来了扩展能力插件丰富够用且易写扩展强但学起来慢强但要会写前端组件与 GitHub Pages 配合极佳零配置部署需要额外配置需要额外构建步骤所以我的建议是团队里如果 Python 开发有一定基础或者想尽量少引入前端构建链MkDocs 直接冲。它内置的mkdocs serve能实时预览改完 Markdown 保存就能在浏览器里看到渲染结果这种即时反馈对写文档的人来说太重要了。1.2 一个最基本的 MkDocs 项目长什么样我不想一上来就讲理论先把最小可运行的项目摆出来。你只要装好 Python 3.8 以上版本然后执行pip install mkdocs mkdocs new my-docs cd my-docs这条命令会生成这样的目录结构my-docs/ ├── mkdocs.yml └── docs/ └── index.mdmkdocs.yml是项目的配置文件类似静态站点生成器的总开关。打开它你会看到默认内容site_name: My Docs然后执行mkdocs serve浏览器打开http://127.0.0.1:8000就能看到默认主题下的文档站点。就这么简单从什么都没有到文档网站跑起来不超过两分钟。我用这个最小示例做教学时几乎所有人都能秒懂 MkDocs 的核心理念它不生产内容它只是把 Markdown 文件按你定义的导航结构整理成网页。真正的工作量永远在写文档本身MkDocs 帮你省掉的是排版、目录、部署这些苦力活。2. 配置 mkdocs.yml站点信息、导航、主题与插件MkDocs 的绝大部分能力集中在mkdocs.yml这一个文件里。把这里面的配置搞明白你基本就掌握了 MkDocs 的 80%。2.1 站点元信息与导航结构我个人的习惯是一开始就配好导航不然后面 Markdown 文件一多nav项很容易漏加。下面是一份我常用的配置模板site_name: 我的项目文档 site_description: 项目说明、接口文档与部署手册 site_author: yourname repo_url: https://github.com/yourname/your-repo repo_name: GitHub nav: - 首页: index.md - 快速开始: - 安装: quickstart/install.md - 第一个示例: quickstart/first-demo.md - API 文档: - 鉴权说明: api/auth.md - 用户接口: api/user.md - 部署手册: deployment.md注意nav里写的是 docs 目录下的相对路径层级关系靠缩进和冒号体现。这样配置之后左侧的侧边导航栏就会按你定义的顺序展示。如果你不写navMkDocs 会自己扫 docs 目录下的文件按文件名生成一个扁平列表。对于小项目可以但对于大型项目强烈建议手写nav因为文档的组织顺序本身就是一种信息架构设计值得花时间梳理。2.2 主题选择Material 主题的配置细节默认主题其实是 MkDocs 自带的但视觉效果非常朴素。我试过的几款主题里个人最推荐Material for MkDocs这也是社区公认的最完善的主题。安装方式pip install mkdocs-material然后在mkdocs.yml里切换theme: name: material language: zh palette: - scheme: default primary: indigo toggle: icon: material/brightness-7 name: 切换到深色模式 - scheme: slate primary: indigo toggle: icon: material/brightness-4 name: 切换到浅色模式 features: - navigation.tabs - navigation.top - search.suggest - search.highlight这里我特别说明几个配置项的用途language: zh让搜索功能支持中文分词这个一定要设否则中文搜索体验会很差。palette定义浅色和深色两套配色用户可以在页面上手动切换。featuresnavigation.tabs把一级导航变成顶部标签页navigation.top在页面滚到底部时显示一个返回顶部的浮动按钮。2.3 常用插件组合我的生产级mkdocs.yml中插件部分长这样plugins: - search - git-revision-date-localized: enabled: !ENV [CI, false] type: date - minify: minify_html: true minify_js: true minify_css: truesearch内置搜索插件开启后右上角出现搜索框按关键词全文检索。git-revision-date-localized自动读取文档文件最近的 Git 提交日期并显示在页面底部。这里加了一个小技巧在 CI 环境下通过!ENV [CI, false]把功能关掉因为 GitHub Actions 里 clone 的代码默认只有当前 commit 的浅历史不关掉会报错或者显示错误时间。minify压缩 HTML、CSS、JS减少站点体积。需要提醒的是插件安装还是那一步pip install mkdocs-material mkdocs-git-revision-date-localized mkdocs-minify-plugin最稳妥的做法是把所有依赖写进requirements.txt这样后续不管是本地还是 CI 环境都能一键安装、版本一致mkdocs1.5.3 mkdocs-material9.5.7 mkdocs-git-revision-date-localized1.2.1 mkdocs-minify-plugin0.7.1版本号务必锁死。我遇到过不止一次插件升级后语法变化导致构建失败CI 直接飘红。3. 用 GitHub Actions 实现自动化部署的完整思路当我们说自动化部署的时候本质上是希望在某个事件触发后服务器自己去完成一系列固定动作。对应到 GitHub 生态里这个服务器就是 GitHub 托管的 runner事件通常是push到主分支动作就是安装依赖 → 构建文档 → 上传产物 → 发布到 Pages。3.1 工作流文件的构成在项目根目录下创建.github/workflows/docs.yml文件文件名随意但建议能一眼看出用途。完整内容如下name: Deploy MkDocs to GitHub Pages on: push: branches: - main workflow_dispatch: permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 with: fetch-depth: 0 - name: Configure Pages uses: actions/configure-pagesv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install --upgrade pip pip install -r requirements.txt - name: Build run: mkdocs build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: site - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pagesv4这段配置看起来长但拆分下来逻辑很清晰on.push.branches指定只在main分支收到 push 时触发。permissions给当前工作流分配权限。pages: write是部署到 GitHub Pages 的必需权限id-token: write是用于 OIDC 安全认证的不写这个deploy-pages会失败。concurrency避免多个提交同时触发部署时互相抢占资源。actions/checkoutv4这一步我专门加了fetch-depth: 0。原因前面提过如果不拉取完整历史MkDocs 的git-revision-date-localized插件没法读取文档对应的最后修改时间。3.2 构建产物与 Pages 部署的解耦注意我把构建和部署分开写了。mkdocs build会在项目目录下生成一个site文件夹里面是纯静态文件。upload-pages-artifact把这个文件夹打包上传deploy-pages再把这份产物发布出去。这样设计的好处是即使部署失败构建产物也已经存在方便排查是构建问题还是发布问题同时 GitHub 的 Pages 部署机制要求你必须通过 artifact 方式上传而不是直接推送文件。3.3 第一次部署前的仓库设置这一步是最容易卡住的。如果直接 push 代码工作流会跑但最后一步deploy-pages大概率报错或者部署到奇怪的地方。你需要打开仓库的Settings → Pages在Build and deployment区域把Source改成GitHub Actions。这告诉 GitHubPages 的发布方式由 Actions 工作流负责而不是从 gh-pages 分支直接托管文件。这个设置和旧版的mkdocs gh-deploy部署方式有本质区别。旧方式是把渲染好的静态文件推到 gh-pages 分支靠 Pages 直接托管分支内容新版则是跑完 Actions 后由 Pages 服务消费上传的 artifact。两种方式都能跑通但新版更符合 GitHub 官方推荐的现代实践而且不用在仓库里保留一个多余的 gh-pages 分支历史。4. 增强自动化多分支、版本切换与 PR 预览基础版本跑通之后我建议再往两个方向深化一是引入拉取请求预览二是做多版本文档切版。这两件事做对了团队协作的效率会有质的提升。4.1 拉取请求预览让文档评审不再是盲改文档出错的场景和代码其实是一样的写的时候觉得自己说明白了等合并到主线才发现链接坏了、代码块渲染错了、导航层级乱了。所以我在基础工作流的基础上加了第二个工作流文件.github/workflows/pr-preview.ymlname: PR Preview on: pull_request: types: [opened, synchronize, reopened] permissions: contents: read pages: write id-token: write jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/configure-pagesv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: pip install -r requirements.txt - name: Build run: mkdocs build - name: Upload artifact uses: actions/upload-pages-artifactv3 with: path: site - name: Deploy preview uses: actions/deploy-pagesv4注意触发条件改成了pull_request。这样每当有人提交 PR系统会自动构建一份临时预览站点PR 的 Checks 区域会出现一个 Pages 预览链接。评审人可以点进链接看到渲染后的效果而不是靠想象去理解 Markdown 转换后的样子。合入 PR 后这个预览会自动失效不需要任何额外清理。4.2 多版本文档的目录设计项目文档一旦开始维护 v1、v2 两个版本目录结构就不能是平铺的了。我习惯把版本作为首层目录docs/ ├── index.md ├── v1.0/ │ ├── index.md │ ├── quickstart.md │ └── api.md └── v2.0/ ├── index.md ├── quickstart.md └── api.md然后在mkdocs.yml里配对应的导航nav: - 首页: index.md - v1.0: - 概述: v1.0/index.md - 快速开始: v1.0/quickstart.md - API: v1.0/api.md - v2.0: - 概述: v2.0/index.md - 快速开始: v2.0/quickstart.md - API: v2.0/api.md这种做法的优点是不需要额外的版本切换插件。缺点是当版本增多时导航会变长。如果只有两三个大版本这种朴素的方案反而最可靠。5. 日常维护与踩坑经验再稳定的自动化流程日常使用中还是会时不时冒出一些奇奇怪怪的问题。我把自己这两年实际踩过的坑总结成几条按出现频率排序希望能帮后面的朋友少折腾几回。5.1 图片资源路径问题这是最容易爆雷的地方。MkDocs 默认把docs目录当作站点根目录所以文档里的图片路径必须相对于docs目录写。比如那么图片文件应该放在docs/assets/architecture.png。如果你在某个子目录里引用图片比如docs/v1.0/quickstart.md想引用 docs 根目录下的 assets 里的图片要写成相对路径我见过很多Markdown 预览没问题、一部署就 404的情况几乎都是这个原因。本地 Markdown 编辑器对相对路径的解析更宽容但部署成静态站点后路径稍有不对就是 404。5.2 中文文件名的问题建议文档文件一律用英文小写命名用连字符分隔。原因是链接和 URL 会包含文件名中文文件名在 URL 编码之后会变得很长很难看而且部分旧版插件在解析中文路径时偶发异常。我实际处理过的一个案例某个文档文件名是支持平台.md本地看起来一切正常部署到 GitHub Pages 后页面上所有指向它的链接都打不开。原因是文件名中的中文字符经过 URL 编码后浏览器和服务器之间的解码存在差异。换成supported-platforms.md之后问题再也没有出现过。5.3 GitHub Actions 构建时间过长构建时间超过 10 分钟的九成是依赖安装太慢。解决方案分两步第一步把requirements.txt里所有依赖的版本号锁死避免每次pip install都要解析最新版本。第二步在pip install后加上缓存- name: Cache pip packages uses: actions/cachev4 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles(requirements.txt) }} restore-keys: | ${{ runner.os }}-pip-依赖没变的情况下后续构建直接从缓存恢复整个安装时间能压到 20 秒以内。5.4git-revision-date-localized插件在 CI 下报错这个问题在 3.1 节提过。具体表现是构建日志里出现ValueError: unable to get current revision date for file xxx.md根因是actions/checkoutv4默认只拉取当前 commit 的浅历史插件读不到更深层的提交记录。解决办法就是我在 checkout 步骤里加的fetch-depth: 0。这是官方文档没怎么强调但实际必须要写的一行。5.5 部署成功但站点没更新这种情况十有八九是浏览器缓存或者 Pages 的 CDN 缓存导致的。GitHub Pages 的缓存刷新不是实时的偶尔会有几分钟延迟。我自己的习惯是部署完成后等两分钟再用无痕窗口检查页面。如果持续十分钟以上没有更新才需要考虑是否构建产物有问题。此时可以打开 Actions 页面点进最近一次工作流查看Upload artifact这个步骤的产物内容确认site/index.html是否是最新的。6. 进阶多仓库复用同一套部署配置最后分享一个团队内部非常实用的扩展思路。如果你的团队有多个项目仓库每个仓库都想要这套 MkDocs Actions 的部署能力不需要每个仓库各自复制一份配置。做法是创建一个模板仓库里面放好template-docs/ ├── .github/ │ └── workflows/ │ └── docs.yml ├── docs/ │ └── index.md ├── mkdocs.yml └── requirements.txt然后用 GitHub 的模板仓库功能把这个仓库设置为 Template。后续新项目创建时直接从这个模板初始化所有配置自动带过去。团队成员只需要替换mkdocs.yml里的site_name和nav加入自己的文档内容push 到 main 分支站点就自动上线了。我最近半年用这种方式帮团队搭了五个项目的文档站总耗时加起来不到一天。相比以前每个项目手工搭部署流程效率提升非常明显而且因为大家用的是同一套模板排错经验也可以共享谁遇到问题答案往往是通用的。如果你现在手上正好有个项目文档还躺在 Word 或者 Wiki 里真的建议花半天时间试一下这套方案。先跑通本地再把 Actions 配置补上你会看到从 push 代码到站点更新这个全自动的过程那种感觉确实很奇妙。