Hugo to GitHub

2023-02-08 1583 words 4 minutes

Contents

通过 GitHub Action 构建 Hugo 自动部署博客到 GitHub Pages

一、使用 Hugo 搭建个人博客

该部分不做具体说明，详情可参考Hugo官方文档

Hugo 常用命令

# 创建新网站 xxx
hugo new site xxx

# 网站主题更换，本网站使用的是LoveIt
# 1.克隆主题到themes目录，把主题存储库作为网站目录的子模块
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt
# 2.向网站配置文件指示当前主题，或直接修改配置文件 (config.toml) 主题字段`theme`
echo "theme = 'LoveIt'" >> config.toml

# 生成新的文章草稿
hugo new posts/my-first-post.md

# 启动开发服务器
hugo server

# 发布网站 在项目根目录中创建整个静态网站
hugo

二、通过 GitHub Action 自动部署博客到 GitHub Pages

通过将代码推送到源码 repo，触发 GitHub Actions 自动运行 Hugo 工作流文件.github/workflows/gh-pages.yml，若运行成功后，则会自动发布到 GitHub Pages repo。

1. 创建代码存储库

我们需要在 GitHub 上创建两个存储库：源码 repo 和 GitHub Pages repo。

源码 repo：
- 私人存储库
- 用于存放博客源码
- 命名无要求
GitHub Pages repo
- 公开存储库
- 用于存放博客静态网页
- 命名规范：<username>/<username>.github.io 将 <username> 替换为你的 GitHub 用户名参考GitHub Pages

2. 创建个人访问令牌

GITHUB_TOKEN 没有权限访问外部存储库，而 deploy_key 或 personal_token 可以。

这里我们选择相对简单点的 personal_token 来创建Personal access tokens ，其中选择范围勾选：repo 和 admin:repo_hook 两项，有效期可以选择永久：No expiration。

3. 源码 repo 中添加 Personal access tokens

源码 repo 的 settings -> Secrets and variables -> Actions
点击 New repository secret， Name 填：ACTION_ACCESS_TOKEN，对应上面工作流配置文件的 personal_token 字段值变量名， Secret 填上面创建的个人访问令牌Personal access tokens

4. 创建源码 repo 的 GitHub Actions 的工作流文件

切换到源码 repo 的 main 分支
在根目录创建一个 .github/workflows/gh-pages.yml 文件（参考使用 GitHub Action 构建 Hugo 和GitHub Pages 部署到外部存储库external_repository ），Demo如下：

name: github pages

on:
  push:
    branches:
      - main  # 这里的意思是当 main分支发生push的时候，运行下面的jobs / Set a branch that will trigger a deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04    # 在什么环境运行任务
    steps:
      - uses: actions/checkout@v3    # 引用actions/checkout这个action，与所在的github仓库同名
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive) 获取submodule主题
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2    # hugo官方提供的action，用于在任务环境中获取hugo
        with:
          hugo-version: 'latest'
          # extended: true

      - name: Build
        run: hugo --minify  # 使用hugo构建静态网页

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3    # 一个自动发布github pages的action
        with:
          # github_token: ${{ secrets.GITHUB_TOKEN }} 该项适用于发布到源码相同repo的情况，不能用于发布到其他repo
          external_repository: <username>/<username>.github.io    # 发布到哪个repo
          personal_token: ${{ secrets.ACTION_ACCESS_TOKEN }}    # 发布到其他repo需要提供上面生成的personal access token
          publish_dir: ./public    # 注意这里指的是要发布哪个文件夹的内容，而不是指发布到目的仓库的什么位置，因为hugo默认生成静态网页到public文件夹，所以这里发布public文件夹里的内容
          publish_branch: main    # 发布到哪个branch

5. 推送远程触发 GitHub Actions

上述步骤完成后，需要先在本地执行 hugo server 确保网站运行正常。
将 Hugo 博客代码和上述配置文件提交并推送到 GitHub 的源码 repo 后，可在 Actions 里看到上面的任务会自动运行。（若 Actions 运行报错，请检查第一步运行后生成的文件是否一起推送到 GitHub。）
上述步骤运行成功后，会自动发布到 GitHub Pages repo，等待该 repo 构建成功后，则可直接访问https:// .github.io查看博客网站。

针对主题无法调整问题！！！

背景

有些主题可能太久没更新，导致与 Hugo 版本不兼容问题。
想给主题加入新元素（比如自动根据文本生成图表，效果）但是又不能改主题代码。

解决

Fork 主题仓库到自己 GitHub，调整代码以解决版本问题，加入新元素等问题，推送代码。

将 Hugo 主题改成自己版本的主题。

# 删除存储在存储库中的本地子模块配置，引用子模块的行将从您的 .git/config 文件中删除。
$ git submodule deinit <submodule>
# 从工作目录和剩余的 .git 文件夹中删除子模块文件。
$ git rm <submodule>
# 还有 .git/modules/themes/<submodule>
rm -rf .git/modules/themes/<submodule>

更换新主题

git submodule add https://github.com/<Your Github>/LoveIt.git themes/LoveIt

完成