Github Action：PNPM单仓库文档包部署成Github Page

2023-10-08 13:31:52

前言

最近需要将一个前端工程移交出去给其他小伙伴接手。因为这个工程一直在内部孵化，除了少数维护的几个人可能知根知底，对于其他人来说，这个工程可能一片空白。因此，我们需要提供一个文档体系来辅助其他小伙伴上手。

我们将采用 Docu 来维护文档，因为它具有以下优点：

基于 Markdown，易于编写和维护。
支持多种格式，包括 HTML、PDF、Word 和 ePub。
可以生成在线文档网站，方便访问和分享。

安装 Docu

在开始部署文档之前，我们需要先安装 Docu。Docu 的安装非常简单，只需在命令行中输入以下命令即可：

npm install -g docu

初始化 Docu 项目

安装 Docu 后，我们就可以初始化一个 Docu 项目了。在项目根目录下，执行以下命令：

docu init

这将创建一个名为 .docu 的目录，其中包含 Docu 的配置文件和一些其他文件。

编写文档

现在，我们可以开始编写文档了。在 .docu 目录下，创建一个名为 docs 的目录，用于存放文档文件。在 docs 目录下，创建一个名为 index.md 的文件，作为文档的首页。

在 index.md 文件中，我们可以使用 Markdown 语法编写文档。Docu 支持多种 Markdown 扩展，可以让我们轻松地创建丰富的文档内容。

部署文档

当我们编写好文档后，就可以将其部署到 Github Page 上了。Github Page 是 Github 提供的免费静态网站托管服务，我们可以轻松地将我们的文档网站部署到 Github Page 上。

要在 Github Page 上部署文档，我们需要先在 Github 上创建一个仓库。然后，在仓库的根目录下，创建一个名为 docs 的分支。最后，将 docs 目录下的所有文件提交到 docs 分支上。

提交完成后，Github Page 会自动将我们的文档网站部署到 https://<username>.github.io/<repository-name> 上。

使用 Github Action 自动化部署

为了方便地维护和更新文档，我们可以使用 Github Action 来自动化部署文档。Github Action 是 Github 提供的持续集成和持续交付服务，我们可以使用它来定义和执行各种自动化任务。

要在 Github Action 中自动化部署文档，我们需要创建一个名为 .github/workflows 的目录，并在其中创建一个名为 deploy.yml 的文件。在 deploy.yml 文件中，我们可以使用 YAML 语法定义我们的部署任务。

name: Deploy Docs

on:
  push:
    branches:
      - docs

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install Docu
        run: npm install -g docu

      - name: Generate Docs
        run: docu build

      - name: Deploy Docs to Github Pages
        uses: JamesIves/github-pages-deploy-action@3.7.1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages
          FOLDER: docs/.docu/public

在这个工作流中，我们定义了一个名为 deploy 的任务，该任务将在每次 docs 分支被推送时触发。在该任务中，我们首先使用 actions/checkout@v2 操作检出仓库代码。然后，使用 npm install -g docu 操作安装 Docu。接着，使用 docu build 操作生成文档。最后，使用 JamesIves/github-pages-deploy-action@3.7.1 操作将文档部署到 Github Page 上。