前言

前段时间听说了 JetBrains Writerside 可以构建产品文档，对其来了兴趣，于是特地研究了一段时间，给我开发的 IDEA 插件整了个产品文档出来，有兴趣的同学可以去看看 ZhiYouToolkit 。

Writerside 是基于 IntelliJ 平台的 JetBrains 集成开发环境。使用它可以编写、构建、测试和发布技术文档。

值得一提的是，Writerside 既有 JetBrains IDE 插件版本，也提供了独立应用。

不过目前我个人感觉知名度没那么广，但就写文档这一块，我认为它应该是最简单的那种，基本不需要做其他事情，打开应用（插件）即可编写页面。

本文主要讲如何自动化部署，关于如何使用它，这里就不过多赘述了。

问题

当我使用 Writerside 编写完文档，我发现我居然要自己打包静态文件发布，这怎么能忍！我直接开始扒官方文档，功夫不负有心人，倒是让我找到了关于 如何利用 Github Action 自动化部署至 Github Pages 的教程。

但是由此又出现了一个问题，因为我并没有使用 Github Pages 托管我的静态页面（主要是太慢了），我用的是 Cloudflare Pages，相信用过这个的都应该清楚，它提供了很多预设框架功能，比方说 Vitepress、docusaurus 什么的，单单就是没有 Writerside，所以关于自动化部署只能自己想办法了。

实现

我仔细查看了官方文档中利用 Github Action自动化部署 Writerside 的操作，我发现 JetBrains 定义了一个Action：JetBrains/writerside-github-action，可以通过这个 Action 将文档转换并打包为静态页面文件。接着我又在 Cloudflare 中发现，可以通过 wrangler 进行静态页面的部署。并且 Cloudflare 也提供了一个 Action cloudflare/wrangler-action，用于远程发布页面。

于是乎，我开始编写能够一键自动化部署的 Github Action 工作流。

前提

需要定义全局变量，以供不同流程的执行。

env:
  # `Writerside/` 固定不变，需要将 `zhiyou` 变更为你的 INSTANCE ID
  INSTANCE: 'Writerside/zhiyou'
  # Writerside 打包你的文档会把静态文件压缩起来，与Writerside应用中打包出来的压缩包名称保持一致
  ARTIFACT: 'webHelpZHIYOU2-all.zip'
  DOCKER_VERSION: '241.16003'
  # 这个我暂时没用到，是关于 algolia 站内搜索的，暂时不用管
  ALGOLIA_ARTIFACT: 'algolia-indexes-ZHIYOU.zip'

注意

1. 一个 INSTANCE 就是一个文档项目。图中我有两个文档，那就代表有两个 INSTANCE，并且 ID 是不一致的。

1. 指定正确的 压缩文件名。正常的压缩文件名是这样的 webHelpXX2-all.zip，把你的 INSTANCE ID 全大写替换掉 XX 即可。例如我的就是 webHelpZHIYOU2-all.zip。

构建文档

先放脚本，再慢慢讲。

# 构建
build:
  runs-on: ubuntu-latest
  steps:
    # 签出代码（工作流会把你的代码拉到指定容器中）
    - name: Checkout repository
      uses: actions/checkout@v4
      with:
        # 因为我是私有仓库，所以需要设置一个Token以供访问
        token: ${{ secrets.GH_TOKEN }}

    # 构建Writerside文档
    - name: Build docs using Writerside Docker builder
      uses: JetBrains/writerside-github-action@v4
      with:
        # 在这里引用了上面定义的变量，这个流程执行完后会生成静态页面的压缩包
        instance: ${{ env.INSTANCE }}
        artifact: ${{ env.ARTIFACT }}
        docker-version: ${{ env.DOCKER_VERSION }}

    # 将构建的文档上传至当前任务的Artifacts
    - name: Save artifact with build results
      uses: actions/upload-artifact@v4
      with:
        # 定义压缩文件名
        name: docs
        # 指定压缩哪些文件
        path: |
          artifacts/${{ env.ARTIFACT }}
          artifacts/report.json
          artifacts/${{ env.ALGOLIA_ARTIFACT }}
        retention-days: 7  # 保存7天

注意

1. 签出代码阶段，公共仓库啥都不用管，但私有仓库需要提供一个Token令牌，怎么申请呢？

   • 在 Github 点击你的头像，在右侧弹出窗选择 Settings，进入设置界面。
   • 观察左侧菜单栏，往下拉，找到最后一个 Developer settings，进入点击 Personal access tokens。
   • Github 提供了两种令牌：Fine-grained tokens（细化权限）、Tokens (classic)（传统令牌）
   • 选择哪种看个人，我选择的是 Fine-grained tokens，可以自定义为此令牌开放哪些权限、库之类的，但它最多只有一年时间。

2. ${{ secrets.GH_TOKEN }}是啥？

   对于工作流来说，在执行时难免要用到一些私密参数，譬如现在说的 Token 令牌，这种参数基本不可能明文定义在工作流上，所以 Github 提供了一个功能，让你存放一些私密参数。

   • 进入你的仓库主页，打开 Settings，观察左侧菜单栏，找到 Secrets and variables，并打开下级菜单 Actions。
   • 点击 New repository secret 新增密钥，定义好参数及名称即可。

验证文档

除此以外，JetBrains 还提供了一个 验证文档 的 Action，当文档存在问题，直接中断流程。

# 验证 Writerside 是否存在错误，存在即中断流程
test:
  needs: build
  runs-on: ubuntu-latest
  steps:
    - name: Download artifacts
      uses: actions/download-artifact@v4
      with:
        # 上面流程提到将生成的文件上传至 artifacts 中，于是这里我们从 artifacts 把文件下载下来。
        name: docs
        path: artifacts

    - name: Test documentation
      uses: JetBrains/writerside-checker-action@v1
      with:
        instance: ${{ env.INSTANCE }}

上传至 Cloudflare

# 部署至Cloudflare
deploy:
  # 当前两个流程走完了再走
  needs: [build, test]
  runs-on: ubuntu-latest
  name: Deploy Cloudflare
  steps:
    # 这里同样下载先前定义的artifact docs 
    - name: Download artifact
      uses: actions/download-artifact@v4
      with:
        name: docs

    # 因为打包时是把静态文件统一压缩至一个压缩包内
    # 现在需要解压出来，以供上传至 Cloudflare Pages 中
    - name: Unzip artifact
      run: |
        # 解压 artifacts 中的 web静态文件
        unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d web-src

    - name: Deploy
      uses: cloudflare/wrangler-action@v3
      with:
        # 这里就是部署了，同样需要在 Cloudflare 申请一个 Token 令牌
        apiToken: ${{ secrets.CF_TOKEN }}
        # 这里就是指定部署命令，有几点需要注意：
        #  - web-src: 这个就是上一步骤 [解压web静态文件] 中解压后，存放静态文件的目录
        #  - zhiyou-docs: 这个其实就是你在 Cloudflare 中创建的应用的名称
        command: pages deploy web-src --project-name=zhiyou-docs

注意

1. 在 build 流程中定义上传了一个 artifact，名称是 docs，那么之后的流程想要下载这个，也必须指定该名称。这其实就是每个流程都使用了不同的容器进行指令执行，文件必然也不共享，所以临时把 文件上传至 Github Artifact 托管起来，各个流程想要都可以随时获取。

2. 在 Cloudflare 申请 Token 令牌

   • 进入 Cloudflare，进入 我的个人资料，左侧菜单栏点击 API令牌。

   • 点击 创建令牌，这时你会看到若干模板，直接选择 编辑 Cloudflare Workers 模板

   • 这时你会看到 权限 栏已经预设了很多权限，不用管，重点在 帐户资源 及 区域资源 中。

   • 如下图所示，帐户资源 选择 "包括"，在第一个选择框选择你的 管理员账户；区域资源 选择 "包括"，并选择 "帐户的所有区域"，接着选择你的 管理员账户 即可。

   • 将生成出的 token 存放在 Github 密钥管理那里供 工作流读取即可。

结果

这样的话就大功告成，提交代码至 Github 就会自动执行流程了。如果有多个 INSTANCE 在同一项目中，那么就定义多个 工作流 去跑不同的文档即可，反正我这里每次上传代码就会同时部署 中英文档。

这篇大概不会有多少人看，主要是用 Writerside 的太少了！！！

还是希望能支持一下我，给我的插件项目 ZhiYouToolkit 点个星，我就心满意足了。

在下面贴一下完整代码内容。

完整代码

name: Build Chinese documentation

on:
  push:
    branches: ["main"]
    paths-ignore:
      - '.github/**'
  workflow_dispatch:

permissions:
  id-token: write

# 定义变量
env:
  INSTANCE: 'Writerside/zhiyou'
  ARTIFACT: 'webHelpZHIYOU2-all.zip'
  DOCKER_VERSION: '241.16003'
  ALGOLIA_ARTIFACT: 'algolia-indexes-ZHIYOU.zip'

# 任务
jobs:
  # 构建
  build:
    runs-on: ubuntu-latest
    steps:
      # 签出代码
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GH_TOKEN }}

      # 构建Writerside文档
      - name: Build docs using Writerside Docker builder
        uses: JetBrains/writerside-github-action@v4
        with:
          instance: ${{ env.INSTANCE }}
          artifact: ${{ env.ARTIFACT }}
          docker-version: ${{ env.DOCKER_VERSION }}

      # 将构建的文档上传至当前任务的Artifacts
      - name: Save artifact with build results
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: |
            artifacts/${{ env.ARTIFACT }}
            artifacts/report.json
            artifacts/${{ env.ALGOLIA_ARTIFACT }}
          retention-days: 7  # 保存7天

  # 验证 Writerside 是否存在错误，存在即中断流程
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: docs
          path: artifacts

      - name: Test documentation
        uses: JetBrains/writerside-checker-action@v1
        with:
          instance: ${{ env.INSTANCE }}

  # 部署至Cloudflare
  deploy:
    needs: [build, test]
    runs-on: ubuntu-latest
    name: Deploy Cloudflare
    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: docs

      - name: Unzip artifact
        run: |
          # 解压 artifacts 中的 web静态文件
          unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d web-src

      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_TOKEN }}
          command: pages deploy web-src --project-name=zhiyou-docs