[Github Action]PNPM monorepo docs package部署成Github Page

前言

最近需要把一个前端工程转交出去给其他小伙伴接手；因为一直在内部孵化，基本除了少数维护的几个人可能知根知底；而对于其他人来说一片空白，所以需要提供一个文档体系来辅助别人上手；

文档维护采用docusaurus来搭建，代码在Github，所以想把Github Page利用起来；又因为采用monorepo子包的方式维护，看了下社区没有相关部署姿势，就写了这么一篇；

效果图

Github Action 执行过程

文档存放及部署分支

访问效果

工程信息

• 依赖采用PNPM v8来统一管理
  • monorepo机制也是采用pnpm默认提供的
• 文档不是在根目录（比如docs目录这种），是当做一个monorepo package来维护，如图

需要解决问题

因为我们把文档做成一个monorepo 子包来维护了，所以对应的产物也在包内；常规的Github Page只能读取工程根目录或者根目录下的docs文件夹，此时就没法直接通用了，如下图所示；翻了翻【docusaurus deployment】官方的部署文档的指南，发现并没有针对monorepo的指导；

但是办法总比困难多，知道了Github Page的部署机制，其实就有法子绕过去了；

• gh-pages: 是github官方默认推荐的静态站点存放分支
• 文档入口默认读取根目录

结合这两点，我们可以利用Github Action来帮我们实现这个需求！

如何实现？

1. 写一个Github Action的工作流
   1. 监听分支【一般是主干线，不过也可以自己喜好，这边采用docs】
      1. 一般更为合理的是标签（git tag）或者主干线
   2. 设置pnpm及node的版本
   3. 安装依赖
   4. 打包文档工程
   5. 推送到远端并部署
2. docusaurus 部署配置（用于Github Page正确识别）
   1. 设置Github 组织名（个人就用户名，组织就组织名）
   2. 设置url 和baseUrl
      1. 前者是部署域（github就是github 生成page主域）
      2. baseUrl是工程的入口网页的寻址路径

Github Workflow

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - docs
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: 'pnpm'
      - name: Install dependencies
        run: |
          cd ./packages/docs # monorepo 需要切换到对应的包路径进行相关操作！！切记！！！
          pnpm install --frozen-lockfile
      - name: Build monorepo-docs-website
        run: |
          echo ${{ github.workspace }}  # 输出工作区上下文路径，就是工程路径
          cd ./packages/docs
          pnpm build

      # Popular action to deploy to GitHub Pages:
      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Build output to publish to the `gh-pages` branch:
          publish_dir: ./packages/docs/build # 文档打包产物的目录名就是build
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'
          commit_message: ${{ github.event.head_commit.message }}

docusaurus.config.js

主要关注：url ， baseUrl ， organizationName ，projectName

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'XXXXX FE SITESPEED',
  tagline: '前端场景性能测试方案',
  favicon: 'img/favicon.ico',

  // Set the production url of your site here
  url: 'https://xxxxxx.github.io', // github page 分配的访问域
  // Set the /<baseUrl>/ pathname under which your site is served
  // For GitHub pages deployment, it is often '/<projectName>/'
  baseUrl: '/xxxxx/',  // github 仓库的名字

  // GitHub pages deployment config.
  // If you aren't using GitHub pages, you don't need these.
  organizationName: 'xxx', // Usually your GitHub org/user name.
  projectName: 'xxxx', // Usually your repo name.
  trailingSlash: false,

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',

  // Even if you don't use internalization, you can use this field to set useful
  // metadata like html lang. For example, if your site is Chinese, you may want
  // to replace "en" with "zh-Hans".
  i18n: {
    defaultLocale: 'zh-Hans',
    locales: ['zh-Hans']
  },
};

module.exports = config;

总结

有不对之处请留言，会及时修正，谢谢阅读