Hugo

Hugo 是一个可以快速构建静态网站的框架，我们可以参考 Quick Start | Hugo 来快速上手 Hugo。

安装 Hugo

Hugo 官方文档推荐使用包管理器来安装 Hugo。

在 macOS 下，我们一般使用 Homebrew 包管理器。

brew install hugo

在 Windows 下，我们可以使用 Chocolatey、Scoop 等包管理器来安装 Hugo。

安装完成后，我们可以在终端执行 hugo 命令。

hugo version

使用 Hugo 创建网站

通过执行以下命令，我们将在当前路径下创建 hugo-blog 文件夹，文件夹中包含新创建的网站代码。

hugo new site hugo-blog

为网站添加主题

我们可以在 themes.gohugo.io 网站上选择适用于 Hugo 框架的博客主题，本站使用的是 Hugo PaperMod 主题，主题文件存放在 hugo-blog 文件夹中的 theme/hugo-PaperMod-6.0 路径下。我们可以直接下载主题文件，也可以使用 git submodule add 命令添加主题文件的 git repo。

然后，我们需要在 config 文件中添加对网站主题的设置。

echo "theme = 'hugo-PaperMod-6.0'" >> config.toml

为网站添加内容

通过在网站的主目录 hugo-blog 下执行以下命令，Hugo 将在子目录 content 下创建 posts 目录，然后在 posts 目录中创建 hello-world.md 文件。

hugo new posts/hello-world.md

Hugo 会在 hello-world.md 文件中添加文件头。

---
title: "Hello World"
date: 2022-09-20T17:10:41+08:00
draft: true
---

draft: true 表示该文件为草稿，默认不会被 Hugo 渲染。

在本地启动 Hugo 服务器

通过执行以下命令，我们可以在本地运行 Hugo 服务器，网站的 url 为 http://localhost:1313/。

hugo server

若需要渲染草稿，可以为命令添加 -D 参数。

hugo server -D

构建网站页面

通过执行以下命令，Hugo 将在 public 目录下生成网站的静态页面。

hugo

我们可以通过添加 -D 参数来渲染仍是草稿的文件内容。

hugo -D

将 public 作为 Github Pages 的 local repo push 至 remote 后，即可访问我们通过 Hugo 生成的 Github Pages。

Github Actions

我们可以借助 Github Actions，在 push Hugo source repo 至 Github 时，自动部署 Github Pages。我们可以参考 peaceiris/actions-hugo 来进行 Hugo 的 Github Actions 的设置。

配置 Github Actions

若要使用 Github Actions，我们可以通过在 Hugo source repo 中新建 .github/workflows 路径，然后在该路径中添加 Github Actions workflows 配置文件来实现。配置文件可以使用 yaml 格式。推送 repo 至 Github 后，我们可以在 Actions 中查看我们所添加的 Github Actions workflow。

以下是本站所使用的部署 Hugo repo 至 Github Pages 的配置：

name: github pages

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

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

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: wang-hz/wang-hz.github.io
          publish_branch: master
          publish_dir: ./public

为 Github repos 添加密钥

Hugo repo 通过 Github Actions 构建 Github Pages 时，需要通过密钥来验证部署权限。我们可以使用 ssh-keygen 命令在本地生成密钥对，然后添加到 Github repos 中以供构建时使用。

在 Hugo 网站的 Github repo 页面中，我们通过 Settings -> Secrets -> Actions 来添加私钥，私钥名需要与 Github Actions workflows 配置文件中的密钥名字保持一致。

在 Github Pages 的 Github repo 页面中，我们通过 Settings -> Deploy keys 来添加公钥，公钥名可自由设置。