WriterSide 文档、接口自动编译并部署到GitPage

1. GitHub 创建空仓库

在 GitHub 创建一个空的仓库

仓库创建成功后， 记录仓库的远程地址

仓库地址需要修改为自己的仓库地址， 比如我的仓库地址为

git remote add origin git@github.com:demodeom/write-auto-test.git

2. 配置GitHub 仓库的编译部署方式

设置仓库编译部署的方式为 GitHub Actions

3. WriteSide 创建项目

打开软件 WriteSide 创建项目

创建项目时， 项目存储目录 和 项目目录名可以自定义

4. 创建自动、编译部署配置文件

1. 编辑器左边的工具条， 切换到 project 图表
2. 文件展示方式 选择 Peoject Files
3. 创建自动 编译部署 配置文件
   1. 在项目根目录 创建目录 .github
   2. 在 .github 目录下创建目录 workflows
   3. 在 workflows 目录下创建文件 build-docs.yml
      

正确的 build-docs.yml 文件内容如下

name: Build documentation

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  id-token: write
  pages: write

env:
  INSTANCE: 'Writerside/in'
  ARTIFACT: 'webHelpIN2-all.zip'
  DOCKER_VERSION: '241.18775'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - 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 }}

      - name: Save artifact with build results
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: |
            artifacts/${{ env.ARTIFACT }}
            artifacts/report.json
          retention-days: 7
  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 }}
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: [build, test]
    runs-on: ubuntu-latest
    steps:
      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: docs

      - name: Unzip artifact
        run: unzip -O UTF-8 -qq '${{ env.ARTIFACT }}' -d dir

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Package and upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dir

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

build-docs.yml 文件内容模板可以在 官方文档找到， 官方文档地址 https://www.jetbrains.com/help/writerside/deploy-docs-to-github-pages.html

2025年5月18日测试， 官方已经默认ID修改为hi, 因此无需再做以下修改

需要注意， 截止 2024 年 8 月 7 日， 官方文档提供的配置文件模板有两处错误
错误1： 默认的 instance_name 是 in ， 并不是文档上所说的 hi
错误2： ARTIFACT 文件名与 INSTANCE 的值相关， 所以也需要修改
修改正确的

env:
  INSTANCE: 'Writerside/in'
  ARTIFACT: 'webHelpIN2-all.zip'
  DOCKER_VERSION: '241.18775'

官网文档错误的

env:
  INSTANCE: 'Writerside/hi'
  ARTIFACT: 'webHelpHI2-all.zip'
  DOCKER_VERSION: '241.18775'

5. 自动编译、部署

代码推送到 GitHub 之后， 会自动编译部署

以下命令可以在 Writerside 终端执行

第一次提交代码

# 初始化 git 仓库
git init

# 修改当前分支名字为 main
git branch -M main

# 将所有修改过的文件添加到 缓存区
git add .

# 将本地修改的文件提交到本地版本库
git commit -m 'first commit'

# 添加远程仓库地址
git remote add origin git@github.com:demodeom/write-auto-test.git

# 将本地代码推送到远程仓库
git push -u origin main

代码推送到 GitHub 仓库后， 在 Action 页面可以看到，自动编译部署的进度

点击任务 first commit， 可以看到具体的进度

编译、部署完成之后， 可以看到项目地址，点击即可在线访问项目
不同的用户， 不用的项目， 访问地址不一样

项目访问地址规律

https://GitHub用户名.github.io/仓库名

比如：

• 用户名 demodeom
• 仓库名 write-auto-test
• 访问地址 https://demodeom.github.io/write-auto-test