# 如何使用 GitHub Action 自动部署 MKDocs

- Link: https://www.ixiqin.com/2021/01/29/how-to-use-a-lot-action-automatically-deploy-mkdocs/
- Published: 2021-01-29T00:34:42+08:00
- Author: 白宦成

文章目录

 [Toggle](https://www.ixiqin.com/2021/01/29/how-to-use-a-lot-action-automatically-deploy-mkdocs/#)

 * [操作流程](https://www.ixiqin.com/2021/01/29/how-to-use-a-lot-action-automatically-deploy-mkdocs/#%e6%93%8d%e4%bd%9c%e6%b5%81%e7%a8%8b)
 * [代码解读](https://www.ixiqin.com/2021/01/29/how-to-use-a-lot-action-automatically-deploy-mkdocs/#%e4%bb%a3%e7%a0%81%e8%a7%a3%e8%af%bb)
 * [总结](https://www.ixiqin.com/2021/01/29/how-to-use-a-lot-action-automatically-deploy-mkdocs/#%e6%80%bb%e7%bb%93)

MKDocs 是一个基于 Python 写成的文档生成工具，在实际的使用过程中，我们可以借助 GitHub
Action 来实现自动部署到 GitHub Pages 。

## 操作流程

首先，你需要先在本地生成一个 MKDocs 项目

![](https://postimg.aliavv.com/mbp2021/qyeuk.png)

生成后， 你可以在项目的根目录创建 GitHub Action 所需目录。

    ```shcb-line-numbers
    mkdir -p .github/workflows/
    ```

并创建一个配置文件 `publish_docs.yml`

    ```shcb-line-numbers
    name: Publish docs via GitHub Pages
    on:
      push:
        branches:
          - main
    jobs:
      build:
        name: Deploy docs
        runs-on: ubuntu-latest
        steps:
          - name: Checkout main
            uses: actions/checkout@v2
          - name: Deploy docs
            uses: mhausenblas/mkdocs-deploy-gh-pages@master
            env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              CONFIG_FILE: mkdocs.yml
              EXTRA_PACKAGES: build-base
    ```

创建完成后，将配置文件添加到版本控制中，并提交到 GitHub 上，就可以在你提交代码的
时候，自动推送到 GitHub Pages 中。

需要注意的是，我使用的是 MKDocs 的 Material Design 主题，如果你使用的是其他主题（
非自带的主题），则需要修改 EXTRA_PACKAGES 的配置。

## 代码解读

这个配置文件中主要是 on 和 steps 比较有学习的价值。

    ```shcb-line-numbers
    on:
      push:
        branches:
          - main
    ```

这段代码限制了，只有在 `main` 分支上，出现了 commit 的时候，才会触发这个 action 
的执行，如果是其他的分支，则不会触发 action 的构建。

    ```shcb-line-numbers
        steps:
          - name: Checkout main
            uses: actions/checkout@v2
          - name: Deploy docs
            uses: mhausenblas/mkdocs-deploy-gh-pages@master
            env:
              GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
              CONFIG_FILE: mkdocs.yml
              EXTRA_PACKAGES: build-base
    ```

这里的两个 step， 第一个是 clone 出所有的代码, 第二个 step 就是我使用一个已经做好
的 action `mhausenblas/mkdocs-deploy-gh-pages@master`,这个 action 的作用就是将 mkdocs
的文档生成并部署到 GitHub Pages 中。

这个 action 自带了 material design 的主题，执行后，会构建并推送到 GitHub Pages。
如果你使用的也是这个主题就可以直接按照我的样式进行配置。如果你使用的不是这个主题，
则需要将你的主题配置在 EXTRA_PACKAGES，从而让 action 在执行的时候安装相应的 package。

## 总结

GitHub Action 的 Marketplace 中有大量的现成 Action 可以供你使用，借助现成的 Action，
你可以非常简单的完成自己的 CI/CD 流程，非常方便。