用 MkDocs + GitHub Actions 自动化部署项目文档

用 MkDocs + GitHub Actions 自动化部署项目文档

写文档不是写README凑合，而是把知识做成「可维护的工程产物」。我的目标很简单：
写 Markdown → push → 自动部署到 GitHub Pages，中间不手动干预、不折腾服务器、不装 Node。

下面先说清两样东西干啥，然后把我的方案（配置 + 原因）贴出来。

一、快速说明：MkDocs 和 GitHub Actions 各干什么

MkDocs

• 静态站点生成器，输入一堆 Markdown，输出一堆静态 HTML（site/目录）。
• 主题用 Material 非常合适：搜索、暗黑模式、代码复制、Mermaid、Tabs、Admonition 等开箱即用。
• 本地可以用mkdocs serve做热预览，用mkdocs build生成静态文件。

GitHub Actions

• CI/CD 工具。我们用它做三件事：检出代码 → 在 runner 上安装 Python 与 MkDocs 依赖 → 运行mkdocs build→ 把site/推到gh-pages分支（用于 Pages）。
• 常见配套：actions/checkout、actions/setup-python、peaceiris/actions-gh-pages（负责把静态文件发布到gh-pages）。

关键思想：把构建行为放到 CI，把发布交给 actions-gh-pages。本地只做编辑与预览，生产环境由 Actions 完成。

我的想法

目标

• main分支 push 自动触发构建并发布到gh-pages。
• 支持：Material 主题、中文/英文搜索、代码块复制、Git 修订日期显示（基于完整 git 历史）。
• Actions 环境：Ubuntu runner + Python 3.11。

设计要点（为什么这样）

1. fetch-depth: 0：必须的——git 插件需要完整历史才能显示创建/修改时间。
2. 在 Actions 里显式pip install需要的插件（Material、awesome-pages、git-revision-date-localized）以避免构建失败。
3. 使用peaceiris/actions-gh-pages统一负责把site/推到gh-pages，简洁可靠。
4. 本地先mkdocs serve调试，Actions 只做非交互式构建与发布。

三、我的mkdocs.yml（直接用的配置 — 把占位符换成你的）

下面是我最终用的mkdocs.yml（照你之前给的大体结构整理，去掉了多余解释，保留功能与插件配置）。你可以直接放到仓库根目录：

site_name:${SiteName}# 替换为站点名site_description:$siteDescriptionsite_author:$SiteAuthorcopyright:"Copyright © $currentYear $SiteAuthor - 保留所有权利"docs_dir:"$DocDir"theme:name:materiallanguage:zhlogo:Awesome-Embedded.pngfavicon:Awesome-Embedded.icopalette:-media:"(prefers-color-scheme: light)"scheme:defaultprimary:indigoaccent:indigotoggle:icon:material/brightness-7name:切换至暗色模式-media:"(prefers-color-scheme: dark)"scheme:slateprimary:blackaccent:indigotoggle:icon:material/brightness-4name:切换至亮色模式font:text:Robotocode:Roboto Monofeatures:-navigation.instant-navigation.instant.prefetch-navigation.instant.progress-navigation.tracking-navigation.sections-navigation.expand-navigation.path-navigation.indexes-navigation.top-navigation.footer-toc.follow-toc.integrate-search.suggest-search.highlight-search.share-content.code.copy-content.code.select-content.code.annotate-content.tabs.link-content.tooltips-content.action.edit-content.action.viewmarkdown_extensions:-abbr-attr_list-def_list-footnotes-md_in_html-tables-toc:permalink:truepermalink_title:链接到此章节slugify:!!python/object/apply:pymdownx.slugs.slugifykwds:case:lower-admonition-pymdownx.details-pymdownx.highlight:anchor_linenums:trueline_spans:__spanpygments_lang_class:truelinenums:truelinenums_style:pymdownx-inline-pymdownx.inlinehilite-pymdownx.superfences:custom_fences:-name:mermaidclass:mermaidformat:!!python/name:pymdownx.superfences.fence_code_format-pymdownx.tabbed:alternate_style:truecombine_header_slug:trueslugify:!!python/object/apply:pymdownx.slugs.slugifykwds:case:lower-pymdownx.emoji:emoji_index:!!python/name:material.extensions.emoji.twemojiemoji_generator:!!python/name:material.extensions.emoji.to_svg-pymdownx.caret-pymdownx.mark-pymdownx.tilde-pymdownx.keys-pymdownx.smartsymbols-pymdownx.snippets-pymdownx.critic-pymdownx.betteremplugins:-search:separator:'[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'lang:-zh-enpipeline:-stemmer-stopWordFilter-trimmer-awesome-pages-git-revision-date-localized:enable_creation_date:truefallback_to_build_date:truetype:datetimetimezone:Asia/Shanghailocale:zhextra:social:-icon:fontawesome/brands/githublink:https://github.com/Awesome-Embedded-Learning-Studioname:GitHub-icon:fontawesome/solid/paper-planelink:$Emailname:发送邮件extra_javascript:-javascripts/mathjax.js-https://polyfill.io/v3/polyfill.min.js?features=es6-https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

说明（要点）：

• docs_dir指向你的 Markdown 源目录（默认docs，可以改）。
• git-revision-date-localized需要fetch-depth: 0才能正确显示创建/更新时间（下面 Actions 已配置）。
• 如果不需要 MathJax，去掉extra_javascript里的 MathJax 条目以加速构建。

四、我的 GitHub Actions 工作流

# 工作流名称name:自动部署 MkDocs# 触发条件：推送到 main 分支on:push:branches:-mainworkflow_dispatch:permissions:contents:writejobs:deploy:runs-on:ubuntu-lateststeps:-name:检出仓库uses:actions/checkout@v4with:fetch-depth:0-name:设置 Pythonuses:actions/setup-python@v5with:python-version:"3.11"-name:安装依赖run:|pip install mkdocs-material pip install mkdocs-awesome-pages-plugin pip install mkdocs-git-revision-date-localized-plugin-name:构建网站run:mkdocs build--clean-name:部署到 GitHub Pagesuses:peaceiris/actions-gh-pages@v4with:github_token:${{secrets.GITHUB_TOKEN}}publish_dir:./site

为什么这样写：

• fetch-depth: 0：让git-revision-date-localized能获取完整历史。
• 明确python-version：避免 runner 默认 Python 版本导致兼容问题。
• 在 Actions 里安装插件：保证构建环境与本地一致（Actions 是一台干净机器）。
• peaceiris/actions-gh-pages用GITHUB_TOKEN推送site/到gh-pages，无需额外 secret。

五、部署 / 测试步骤（你应该怎么做）

1. 在仓库根放mkdocs.yml，把docs/写好（index.md必须有）。
2. 把上面的 workflow 存为.github/workflows/deploy-mkdocs.yml。
3. git add . && git commit -m "add docs site and ci" && git push origin main。
4. 去 GitHub → Actions 看日志，确认mkdocs build成功并且gh-pages分支有更新。
5. 去仓库 Settings → Pages，确保 Pages 来源是gh-pages（通常 peaceiris 会自动设置）。
6. 访问https://<username>.github.io/<repo>/（或你配置的自定义域名）。

结语

这就是我的方案：把 MkDocs 的配置尽量放在mkdocs.yml（功能全开），把构建与发布放到 GitHub Actions（可复现、可审计）。你只要维护docs/下的 Markdown，写文档就像写代码一样——有版本、有历史、有自动化。