Hugo 个人博客搭建

使用 The world’s fastest framework for building websites | Hugo 结合 LoveIt 主题，部署自己的 GitPage 博客 抓鱼

方案核心部分：

1. 在 Github 托管个人博客源仓库，对所有的博客文章进行版本管理，并使用 GitHub Action 进行 CI/CD 部署，自动向 GitHub Pages 仓库进行静态页面的发布
2. GitHub Pages 通过 github.io 网址进行博客网页托管和发布
3. Hugo 主题仓库，使用 git submodule 方法链接到博客源仓库

前言

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

Hugo 是基于 Go 的博客工具，用 markdown 进行文章编辑。

相较于使用 node 的 Hexo 而言，具有编译更快、模块更轻量（众所周知，node_modules 是地球上最重的东西）、发布更简单的优点。而且更不需要使用愚蠢的 node 和 npm 进行管理，实在是令人心动。

安装 & 配置

本文基于 macos 系统描述，其他操作系统请参考项目源文档。

基本安装方法

对 hugo 程序的安装，使用 mac 最标准的 homebrew 进行程序安装和管理。

1

brew install hugo

然后可以使用 hugo version 验证安装成功。

完成安装后，可以用下列命令进行网页的创建

1

hugo new site blog

主题配置

选择 LoveIt 主题进行主题配置，参考 Theme Documentation - Basics - LoveItj 进行细节配置

1
2
3

cd blog
git init
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

[!note] 动态资源放在 asserts 下方，例如头像 avatar.jpeg 静态资源放在 static 下方，例如 params.app.svgFavicon，

更新主题

如果需要对主题仓库进行同步和更新，可以使用 git submodule update --remote

文章发布

hugo 创建文章使用 hugo new posts/POST_NAME.md 进行发布，使用 archetype/default.md 的默认配置，参考 Theme Documentation - Content - LoveIt

本地调试

Hugo 会生成静态网页，本地可以使用 hugo server 进行实时调试预览，无须每次重新生成。注意，post 文件里，draft=true 的 post 不会被渲染，需要使用 hugo server -D 才能显示出来。

运行服务后，可以通过浏览器 http://localhost:1313 访问预览网页

GitPage 发布

仓库构建

在 github 中创建一个<USER_NAME>.github.io 的特殊仓库，然后将配置文件 config.toml 中的 baseURL 改为自己的自定义域名，这样博客就能访问对应的 gitpage 网页。

完成上述准备工作后，我们现在已经可以通过自定义域名来访问我们的 GitHub Pages 页面了，目前因为项目仓库是空的，访问后会报 404 页面。

我们希望 Hugo 生成的静态网站能通过 GitHub Pages 服务进行托管，而无需自己维护服务，更稳定、安全，因此我们需要上传 Hugo 生成的静态网页文件至 GitHub Page 项目仓库。

手动发布

可以执行 hugo 在本地的 public 目录下创建静态网页，通过将 public 目录初始化为 git 仓库，并关联 gitpage 远程仓库，就可以推送网页静态文件。

1
2
3
4
5

git init
git remote add origin git@github.com:<username>/<username>.github.io
git add .
git commit -m "add test"
git push origin main

自动发布

我们的博客基于 GitHub 与 GitHub Pages，可以通过官方提供的 GitHub Action 进行 CI 自动发布。

在仓库目录下建立 .github/workflows/deploy.yml，自动发布示例如下

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

name: github pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true

      - uses: actions/cache@v2
        with:
          path: /tmp/hugo_cache
          key: ${{ runner.os }}-hugomod-${{ hashFiles('**/go.sum') }}
          restore-keys: |
            ${{ runner.os }}-hugomod-            

      - name: Build Web
        run: hugo --minify

      - name: Deploy Web
        uses: peaceiris/actions-gh-pages@v3
        with:
          PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
          external_repository: NIL-zhuang/nil-zhuang.github.io
          publish_branch: main
          publish_dir: ./public
          commit_message: ${{ github.event.head_commit.message }}

然后我们需要建立一个 PERSONAL_TOKEN，开启 repo 与 workflow 权限，在仓库的 Action Secrets 中添加对应 Token，就可以触发推送了。