用 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: $siteDescription
site_author: $SiteAuthor

copyright: "Copyright © $currentYear $SiteAuthor - 保留所有权利"
docs_dir: "$DocDir"

theme:
  name: material
  language: zh
  logo: Awesome-Embedded.png
  favicon: Awesome-Embedded.ico
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换至暗色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换至亮色模式
  font:
    text: Roboto
    code: Roboto Mono
  features:
    - 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.view

markdown_extensions:
  - abbr
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      permalink_title: 链接到此章节
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - admonition
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
      linenums: true
      linenums_style: pymdownx-inline
  - pymdownx.inlinehilite
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      combine_header_slug: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.keys
  - pymdownx.smartsymbols
  - pymdownx.snippets
  - pymdownx.critic
  - pymdownx.betterem

plugins:
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
      lang:
        - zh
        - en
      pipeline:
        - stemmer
        - stopWordFilter
        - trimmer
  - awesome-pages
  - git-revision-date-localized:
      enable_creation_date: true
      fallback_to_build_date: true
      type: datetime
      timezone: Asia/Shanghai
      locale: zh

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/Awesome-Embedded-Learning-Studio
      name: GitHub
    - icon: fontawesome/solid/paper-plane
      link: $Email
      name: 发送邮件

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:
      - main
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 检出仓库
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 设置 Python
        uses: actions/setup-python@v5
        with:
          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 Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          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，写文档就像写代码一样------有版本、有历史、有自动化。