ghaction-github-pages 使用教程

1. 项目介绍

ghaction-github-pages 是一个用于将静态网站部署到 GitHub Pages 的 GitHub Action。它允许用户通过简单的 YAML 配置，自动化地将网站内容推送到指定的 GitHub Pages 分支。该项目由 crazy-max 开发，旨在简化 GitHub Pages 的部署流程，特别适合需要频繁更新和部署静态网站的开发者或团队。

2. 项目快速启动

2.1 安装与配置

首先，确保你已经有一个 GitHub 仓库，并且已经启用了 GitHub Pages 功能。接下来，在你的仓库中创建一个 .github/workflows 目录，并在其中创建一个新的 YAML 文件，例如 deploy.yml。

2.2 基本配置示例

以下是一个基本的配置示例，用于将 public 目录下的内容部署到 gh-pages 分支：

name: website

on:
  push:
    branches:
      - main  # 或者你使用的默认分支

permissions:
  contents: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v4
        with:
          target_branch: gh-pages
          build_dir: public
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

2.3 运行与部署

将上述配置文件提交到你的仓库后，每次当你向 main 分支推送代码时，GitHub Actions 将自动触发部署流程，将 public 目录下的内容推送到 gh-pages 分支，从而更新你的 GitHub Pages 网站。

3. 应用案例和最佳实践

3.1 个人博客

ghaction-github-pages 非常适合用于个人博客的自动化部署。通过简单的配置，你可以轻松地将博客内容推送到 GitHub Pages，实现快速更新和发布。

3.2 开源项目文档

对于开源项目，文档的及时更新非常重要。使用 ghaction-github-pages，你可以将项目文档自动部署到 GitHub Pages，确保用户始终能够访问到最新的文档信息。

3.3 企业官网

小型企业和团队可以使用 ghaction-github-pages 来维护和更新企业官网。通过自动化部署，可以减少手动操作的错误，并提高网站的更新效率。

4. 典型生态项目

4.1 GitHub Actions

ghaction-github-pages 是基于 GitHub Actions 构建的，因此它与 GitHub Actions 生态系统紧密集成。你可以结合其他 GitHub Actions，如 actions/checkout、actions/setup-node 等，构建更复杂的自动化工作流。

4.2 Swagger UI

如果你正在使用 Swagger UI 生成 API 文档，ghaction-github-pages 可以帮助你将生成的文档自动部署到 GitHub Pages，确保文档的实时性和一致性。

4.3 Docusaurus

Docusaurus 是一个流行的静态网站生成器，特别适合用于文档站点。结合 ghaction-github-pages，你可以轻松地将 Docusaurus 生成的网站部署到 GitHub Pages，实现文档的自动化更新和发布。

通过以上步骤和示例，你可以快速上手并使用 ghaction-github-pages 来简化你的 GitHub Pages 部署流程。