使用GitHub Actions在GitHub Pages部署Docusaurus V3

前言

Docusuarus由于同时具有Blog和Doc两种形式,且支持多版本多语言,可以适配很多场景,所以使用的机构和个人越来越多.

官方部署方法适合专业人士,作为非专业人士在部署上有一些专业需求:

• 能够自动生成和部署.
• 空间免费.
• 只使用简单的操作.

Lars仓库中的方法很合适:

使用GitHub Actions自动将仓库内Docusuarus文件生成静态文件并部署到GitHub Pages,需要操作的部分只有将Docusuarus文件上传至GitHub仓库.

这个方法完美的满足了上面那些专业要求,感谢作者Lars!

下面就将介绍这个方法:

[!NOTE]

test

[!IMPORTANT]
与Lars仓库中方法的主要区别: ① 由于Docusaurus V2和V3有些变化,做了更改. ② 由于GitHub Actions一些组件升级,做了更改. ③ 对于可能遇到的一些问题,增加解决方法. ④ 针对Windows系统环境.

---

第一步 生成Docusuarus网站：

方法一:网络生成

• 使用示例仓库模板新建仓库,使用GitHub Desktop克隆到本地.

  或

• 从示例仓库下载(Code->Download ZIP)所有文件到本地,解压缩.

[!IMPORTANT]

① 使用方法一,可以跳过 第三步 部署GitHub Actions 步骤.

② 如果您想使用Docusuarus的最新版本,请使用 方法二 .

方法二:本地生成

Windows本地推荐安装环境:

• Node.js ≥20
• yarn ≥1.22.19

使用以下命令:

yarn create docusaurus <folder-name> classic --typescript

[!IMPORTANT]

① 右键->以管理员身份运行Power Shell.

② <folder-name> 不能是已经存在的文件夹.

③ 检查是否存在 yarn.lock 如果不存在,在 <folder-name> 文件夹下使用以下命令生成此文件:

yarn build

④ node_modules 不用上传至GitHub仓库.

第二步 配置Docusaurus

打开 docusaurus.config.ts .

配置 Url 和 baseUrl .

const config: Config = {
  // (...)
  url: `https://<github-organization-name>.github.io`,
  baseUrl = '/<repository-name>/`;
  };

配置 organizationName 和 projectName .

const config: Config = {
  // (...)
  organizationName: '<github-organization-name>',
  projectName: '<repository-name>',
};

配置Docs和Blog的 editUrl .

const config: Config = {
  // (...)
  presets: [
    [
      "classic",
      {
        docs: {
          // (...)
          editUrl: `https://github.com/<github-organization-name>/<repository-name>/tree/main/`,
        },
        blog: {
          // (...)
          editUrl: `https://github.com/<github-organization-name>/<repository-name>/tree/main/`,
        },
      },
    ],
  ],
};

第三步 部署GitHub Actions

新建: .github/workflows/<workflow-name>.yml 文件并粘贴以下内容:

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: [main]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

env:
  # Hosted GitHub runners have 7 GB of memory available, let's use 6 GB
  NODE_OPTIONS: --max-old-space-size=6144

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn
      - name: Install dependencies
        run: yarn install --frozen-lockfile --non-interactive
      - name: Build
        run: yarn build
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload entire repository
          path: build
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v3

第四步 配置GitHub仓库

选择GitHub Actions为构建和部署源.

GitHub.com -> Repository -> Settings -> Pages -> Build and deployment -> Source -> GitHub Actions

第五步 上传至GitHub仓库

使用GitHub Desktop上传至Repository,等待网站生成.

---