使用 GitHub Workflow 快速构建和部署 MkDocs 项目文档

在项目开发过程中，文档的构建与维护至关重要。借助 GitHub Actions 的强大功能，我们可以实现文档的自动化构建与部署，使得每次代码更新后，项目文档能够自动更新至 GitHub Pages。本篇文章将介绍如何使用 GitHub Workflow 快速构建和部署基于 MkDocs 和 MkDocs Material 主题的项目文档。

为什么选择 MkDocs？

MkDocs 是一个静态站点生成器，专门用于项目文档。它简单易用，且与 Markdown 格式完美兼容。结合 MkDocs Material 主题，你可以轻松打造出一个现代化、响应迅速的文档站点。

安装与初始化 MkDocs 项目

在开始配置 GitHub Workflow 之前，我们首先需要安装 MkDocs 并初始化一个新的项目。

1. 安装 MkDocs

在本地环境中，使用 pip 安装 MkDocs：

pip install mkdocs

2. 初始化 MkDocs 项目

安装完成后，你可以通过以下命令初始化一个新的 MkDocs 项目：

mkdocs new my-project-docs

这会在当前目录下创建一个名为 my-project-docs 的文件夹，其中包含 MkDocs 的基本项目结构。你可以进入该文件夹并运行 MkDocs 开始本地开发：

cd my-project-docs
mkdocs serve

mkdocs serve 命令将在本地启动一个开发服务器，你可以通过浏览器访问 http://127.0.0.1:8000/ 预览文档。

3. 安装 MkDocs Material 主题

为了让文档更加美观，你可以安装 MkDocs Material 主题：

pip install mkdocs-material

然后，在 mkdocs.yml 配置文件中，将主题设置为 material：

site_name: My Project Docs
theme:
  name: 'material'

为什么使用 GitHub Actions？

GitHub Actions 是一个集成于 GitHub 的持续集成/持续交付（CI/CD）平台。通过编写 Workflow，你可以自动化执行构建、测试、部署等任务。在本文中，我们将使用 GitHub Actions 实现 MkDocs 文档的自动化构建与部署。

快速配置 GitHub Workflow

下面是一个完整的 GitHub Workflow 配置示例，用于在推送到 main 分支时自动构建并部署 MkDocs 文档到 GitHub Pages。

1. 创建 Workflow 文件

首先，在你的项目根目录下创建 .github/workflows/gh-pages.yml 文件。这个文件将包含你的 Workflow 配置。

2. 编写 Workflow 配置

在 gh-pages.yml 中编写以下内容：

name: Deploy MkDocs to GitHub Pages
on:
  push:
    branches:
      - main  # 监听 main 分支的推送事件
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v2  # 检出代码
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.8'  # 设置 Python 版本
    - name: Install dependencies
      run: |
        pip install mkdocs  # 安装 mkdocs
        pip install mkdocs-material  # 安装 mkdocs-material 主题
    - name: Build the MkDocs site
      run: mkdocs build  # 构建 MkDocs 网站
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./site  # mkdocs 构建输出目录为 site

3. 配置解读

• name: 工作流程的名称，可以根据需要自定义。
• on: 指定触发工作流程的事件，在这里我们选择了 push 到 main 分支的事件。
• jobs: 定义了工作流程中需要执行的任务（job）。在这个示例中，我们定义了一个 build-and-deploy 的 job，它运行在 ubuntu-latest 的环境中。
• steps: job 内部的具体步骤：
  • Checkout code: 使用 actions/checkout@v2 action 检出代码。
  • Set up Python: 使用 actions/setup-python@v2 action 设置 Python 3.8 环境。
  • Install dependencies: 安装 MkDocs 和 MkDocs Material 主题。
  • Build the MkDocs site: 使用 mkdocs build 命令构建静态网站，输出到 site 目录。
  • Deploy to GitHub Pages: 使用 peaceiris/actions-gh-pages@v3 action 将 site 目录中的内容部署到 GitHub Pages。

4. 配置 GitHub Pages

在 GitHub 仓库中，进入 Settings -> Pages，确保 Source 设置为 gh-pages 分支。如果 gh-pages 分支不存在，GitHub Actions 会自动创建并部署内容到这个分支。

5. 开通 Workflow Permissions

为了确保 GitHub Actions 能够正确部署到 GitHub Pages，你需要在项目的设置中开通 Workflow permissions。

• 进入项目的 Settings 页面。
• 在左侧菜单中找到 Actions 并点击。
• 滚动到 Workflow permissions 部分。
• 选择 Read and write permissions，以便 Workflow 能够推送更改到 gh-pages 分支。
• 勾选 Allow GitHub Actions to create and approve pull requests，以确保 Workflow 可以管理分支。
  保存设置后，GitHub Actions 就可以正常运行并自动部署内容到 GitHub Pages。

6. 提交 Workflow 文件

将创建的 Workflow 文件提交到 main 分支：

git add .github/workflows/gh-pages.yml
git commit -m "Add GitHub Actions workflow for MkDocs deployment"
git push origin main

7. 自动化部署

现在，每次你推送到 main 分支时，GitHub Actions 会自动运行这个 Workflow，构建 MkDocs 网站并将其部署到 GitHub Pages。这样，你的文档站点将始终保持最新，并且每次更新都无需手动干预。

总结

通过 GitHub Actions 的自动化工作流程，我们可以轻松实现项目文档的自动构建与部署。结合 MkDocs 和 MkDocs Material 主题，你能够快速构建一个专业、美观的文档站点，并通过 GitHub Pages 将其发布到互联网。这个过程不仅节省了时间，也确保了文档的持续更新，是现代开发流程中的一项最佳实践。
希望这篇文章能帮助你快速上手 GitHub Actions，构建和部署你的项目文档。如果你有任何问题或建议，欢迎在评论区留言讨论！