Hugo + GitHub 博客自动化部署

创建 GitHub 仓库

一共需要创建两个仓库，分别如下：

简称	名称	用途	Action	Pages
源码仓库	随意，这里以 `你的用户名/blog` 为例	存放 Hugo 博客的源码、文章等，执行 Action 生成静态页面	是	否
页面仓库	必须是 `你的用户名/你的用户名.github.io` 的格式	存放静态页面提供 Web 服务	否	是

源码仓库创建后，需要克隆到本地，稍后将在其中安装 Hugo。

页面仓库创建后，并且打开 Pages 功能，用于静态页面托管。参考官方文档：创建 GitHub Pages 站点 - GitHub 文档

安装 Hugo Extended

参考 Hugo 官网中的安装说明：Installation | Hugo

Windows 可以直接下载安装包：Release · gohugoio/hugo · GitHub

也可以使用 Winget，但需要解决代理问题：

winget install Hugo.Hugo.Extended

安装完了，测试一下：

hugo version

然后安装 Git：Git - Installing Git

顺手装个 Go，或许有用：Download and install - The Go Programming Language

配置 Hugo

添加网站

参考官方文档：Quick start | Hugo

克隆源码仓库到本地，定位到源码仓库的文件夹。

新建 Hugo 站点：

hugo new site MyFreshWebsite --format yaml
# replace MyFreshWebsite with name of your website

添加主题

添加 Hugo 主题，这里使用的是 PaperMod，仓库位于：

GitHub - adityatelange/hugo-PaperMod: A fast, clean, responsive Hugo theme.

使用 Git Submodule 的方法：

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)

# 后续更新主题用这句
git submodule update --remote --merge

修改配置文件 config.yml，添加主题信息：

theme: ["PaperMod"]

然后就可以使用命令启动网站了：

hugo server

添加文章模板

参考 PaperMod 的文档：Installation · adityatelange/hugo-PaperMod Wiki · GitHub

在目录下新建 archetypes/post.md，其中填入：

---
title: "My 1st post"
date: 2020-09-15T11:30:03+00:00
# weight: 1
# aliases: ["/first"]
tags: ["first"]
author: "Me"
# author: ["Me", "You"] # multiple authors
showToc: true
TocOpen: false
draft: false
hidemeta: false
comments: false
description: "Desc Text."
canonicalURL: "https://canonical.url/to/page"
disableHLJS: true # to disable highlightjs
disableShare: false
disableHLJS: false
hideSummary: false
searchHidden: true
ShowReadingTime: true
ShowBreadCrumbs: true
ShowPostNavLinks: true
ShowWordCount: true
ShowRssButtonInSectionTermList: true
UseHugoToc: true
cover:
    image: "<image path/url>" # image path/url
    alt: "<alt text>" # alt text
    caption: "<text>" # display caption under cover
    relative: false # when using page bundles set this to true
    hidden: true # only hide on current single page
editPost:
    URL: "https://github.com/<path_to_repo>/content"
    Text: "Suggest Changes" # edit text
    appendFilePath: true # to append file path to Edit link
---

也可以参考我的配置😀，精简了不常用的选项：

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
slug: "blog-post-slug"
tags: ["tag"]
categories: ["categories"]
description: "Description Text."
draft: true
# author: "Jacob"
# showToc: true
# TocOpen: false
# comments: false
# disableShare: false
cover:
    image: "<image path/url>" # image path/url
---

这里是摘要……

<!-- more -->

从这里开始撰写正文……

添加第一篇文章

hugo new --kind post <name>

个性化配置

然后就是漫长的，个性化修改网站配置 config.yml，PaperMod 可以参考官方 Wiki 中的模板进行修改：

Installation · adityatelange/hugo-PaperMod Wiki · GitHub

baseURL: "https://examplesite.com/"
title: ExampleSite
paginate: 5
theme: PaperMod

enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production # to enable google analytics, opengraph, twitter-cards and schema.
  title: ExampleSite
  description: "ExampleSite description"
  keywords: [Blog, Portfolio, PaperMod]
  author: Me
  # author: ["Me", "You"] # multiple authors
  images: ["<link or path of image for opengraph, twitter-cards>"]
  DateFormat: "January 2, 2006"
  defaultTheme: auto # dark, light
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: false
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: true
  disableSpecial1stPost: false
  disableScrollToTop: false
  comments: false
  hidemeta: false
  hideSummary: false
  showtoc: false
  tocopen: false

  assets:
    # disableHLJS: true # to disable highlight.js
    # disableFingerprinting: true
    favicon: "<link / abs url>"
    favicon16x16: "<link / abs url>"
    favicon32x32: "<link / abs url>"
    apple_touch_icon: "<link / abs url>"
    safari_pinned_tab: "<link / abs url>"

  label:
    text: "Home"
    icon: /apple-touch-icon.png
    iconHeight: 35

  # profile-mode
  profileMode:
    enabled: false # needs to be explicitly set
    title: ExampleSite
    subtitle: "This is subtitle"
    imageUrl: "<img location>"
    imageWidth: 120
    imageHeight: 120
    imageTitle: my image
    buttons:
      - name: Posts
        url: posts
      - name: Tags
        url: tags

  # home-info mode
  homeInfoParams:
    Title: "Hi there \U0001F44B"
    Content: Welcome to my blog

  socialIcons:
    - name: x
      url: "https://x.com/"
    - name: stackoverflow
      url: "https://stackoverflow.com"
    - name: github
      url: "https://github.com/"

  analytics:
    google:
      SiteVerificationTag: "XYZabc"
    bing:
      SiteVerificationTag: "XYZabc"
    yandex:
      SiteVerificationTag: "XYZabc"

  cover:
    hidden: true # hide everywhere but not in structured data
    hiddenInList: true # hide on list pages and home
    hiddenInSingle: true # hide on single page

  editPost:
    URL: "https://github.com/<path_to_repo>/content"
    Text: "Suggest Changes" # edit text
    appendFilePath: true # to append file path to Edit link

  # for search
  # https://fusejs.io/api/options.html
  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    limit: 10 # refer: https://www.fusejs.io/api/methods.html#search
    keys: ["title", "permalink", "summary", "content"]
menu:
  main:
    - identifier: categories
      name: categories
      url: /categories/
      weight: 10
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: example
      name: example.org
      url: https://example.org
      weight: 30
# Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma
pygmentsUseClasses: true
markup:
  highlight:
    noClasses: false
    # anchorLineNos: true
    # codeFences: true
    # guessSyntax: true
    # lineNos: true
    # style: monokai

这里贴一份我的配置😀

baseURL: https://weixiang.github.io/  # 域名
title: Jacob's Thoughts
paginate: 10  # 首页展示文章数量
theme:
  - PaperMod  # 主题
copyright: ©2017-2024 [Jacob's Thoughts](https://weixiang.github.io)  # 页脚
languageCode: zh-cn  # 设置语言代码为中文
hasCJKLanguage: true  # 添加汉字支持
defaultContentLanguage: zh  # 设置默认语言
enableRobotsTXT: true  # 允许搜索抓取
enableEmoji: true  # 添加表情支持
pygmentsUseClasses: true  # 语法高亮
mainsections:
  - posts  # 主要内容位置，SEO 相关
languages:
  zh:
    languageName: 中文
    languageCode: zh
    weight: 1
    taxonomies:
      category: categories
      tag: tags
      series: series
    menu: # 网站右上角菜单
      main:
        - name: 时间
          url: archives
          weight: 1
        - name: 标签
          url: tags
          weight: 2
        - name: 关于
          url: about
          weight: 5
        - name: 搜索
          url: search
          weight: 6
    params:
      DateFormat: 2006 年 01 月 02 日 15:04  # 日期格式本地化
      homeInfoParams:
        Title: Thoughts, stories and ideas.  # 首页大标题
        Content: |
          👋 你好！这里是 Jacob 的博客。
          - 如果你觉得文章写得还不错的话，欢迎通过下面的按钮订阅我。          
outputs:  # 输出设置
  home:
    - HTML
    - RSS
    - JSON
params:
  env: production
  description: Thoughts, stories and ideas.  # 站点描述
  author: Jacob  # 默认作者
  keywords:  # 关键词，SEO 相关
    - blog
    - technical
  defaultTheme: auto  # 自动切换主题
  displayFullLangName: true  # 显示完整的语言名称，多语言用，单语言站点可删除
  ShowBreadCrumbs: true  # 面包屑，SEO 相关
  ShowShareButtons: true  # 分享按钮
  ShowReadingTime: true  # 阅读时间统计
  ShowPostNavLinks: true  # 文章末尾导航栏
  ShowCodeCopyButtons: true  # 代码块复制按钮
  ShowRssButtonInSectionTermList: true  # RSS 按钮显示在分类、系列页面
  ShowAllPagesInArchive: true  # 显示所有页面在时间轴页面
  ShowPageNums: true  # 显示页码
  ShowFullTextinRSS: true  # 在 RSS 中显示全文
  ShowToc: true  # 显示目录
  TocOpen: false  # 自动展开目录
  ShowLastMod: true # 显示最后修改时间，需要主题支持或自己魔改
  comments: true  # 显示评论
  socialIcons:  # 社交软件按钮配置
    - name: GitHub
      url: https://github.com/Weixiang/
    - name: RSS
      url: index.xml
  label:  # 主页左上角网站名称和 Logo
    text: Jacob's Thoughs
    icon: ghost-logo-orb.png
    iconHeight: 35
  analytics: # 搜索引擎站长验证，SEO 相关
    google:
      SiteVerificationTag: XYZabc
    bing:
      SiteVerificationTag: XYZabc
    yandex:
      SiteVerificationTag: XYZabc
  assets:  # 网站图标
    favicon: favicon.ico
    favicon16x16: favicon-16x16.png
    favicon32x32: favicon-32x32.png
    apple_touch_icon: apple-touch-icon.png
    safari_pinned_tab: safari-pinned-tab.svg
  cover:  # 文章封面显示控制
    hidden: false
    hiddenInList: false
    hiddenInSingle: false
  fuseOpts:  # 站内搜索配置
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    keys:
      - title
      - permalink
      - summary
      - content
markup:
  goldmark:
    renderer:
      unsafe: true
  highlight:  # 代码高亮
    noClasses: false
    codeFences: true
    guessSyntax: true
    style: monokai
privacy:  # 第三方服务
  vimeo:
    disabled: false
    simple: true
  twitter:
    disabled: false
    enableDNT: true
    simple: true
  instagram:
    disabled: false
    simple: true
  youtube:
    disabled: false
    privacyEnhanced: true
services:
  instagram:
    disableInlineCSS: true
  twitter:
    disableInlineCSS: true
  disqus: # 评论
    shortname: XYZabc
  googleAnalytics: # Google 统计
    ID: G-XYZabc

使用命令启动网站，检查配置效果：

hugo server

配置 GitHub Action

获取个人令牌

前往 GihHub 个人设置，创建一个 API 令牌：Fine-grained personal access tokens · GitHub

可以参考官方文档：管理个人访问令牌 - GitHub 文档

Repository access 选择 Only select repositories，对象选择刚刚的 你的用户名.github.io。

使用到的权限如下：

Overview
3 permissions for 1 of your repositories

Actions Access: Read and write
Contents Access: Read and write
Metadata Access: Read-only

然后就能得到一串令牌，妥善保存。

添加令牌到仓库

将上一步获取到的令牌添加到源码仓库中。

前往 Settings - Secrets and variables - Actions - Repository secrets，选择 New repository secret，Name 填入 ACTION ，Secret 填入刚刚获取的令牌内容。

参考官方的文档在 GitHub Actions 中使用机密 - GitHub 文档

添加 Action 配置

在源码仓库的文件夹中，新建文件 .github\workflows\deploy.yml，其中添加 Action 配置：

name: Deploy to Github Pages 🚀

on:
    push:
        branches: [main]
    pull_request:
        branches: [main]

jobs:
    build:
        runs-on: ubuntu-latest

        permissions:
            # Give the default GITHUB_TOKEN write permission to commit and push the
            # added or changed files to the repository.
            contents: write

        steps:
            - name: Set Timezone 🌏️
              uses: szenius/set-timezone@v2.0
              with:
                timezoneLinux: "Asia/Singapore"
                timezoneMacos: "Asia/Singapore"
                timezoneWindows: "Singapore Standard Time"

            - name: Checkout 🛎️
              uses: actions/checkout@v4
              with:
                  fetch-depth: 0
                  submodules: true

            - name: Cache Hugo resources 🗃️
              uses: actions/cache@v4
              env:
                  cache-name: cache-hugo-resources
              with:
                  path: resources
                  key: ${{ env.cache-name }}

            - name: Setup Go 🛠️
              uses: actions/setup-go@v5
              with:
                  go-version: "^1.17.0"
            - run: go version

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

            - name: Build 🔧
              run: hugo --minify --gc

            - name: Deploy 🚀
              uses: JamesIves/github-pages-deploy-action@v4
              with:
                  branch: main
                  folder: public
                  clean: true
                  single-commit: true
                  token: ${{ secrets.action }}
                  repository-name: 你的用户名/你的用户名.github.io

发布网站到 GitHub Pages

添加 `.gitignore` 文件

在源码仓库根目录下，新建 .gitignore 文件，其中填入：

public
resources
.hugo_build.lock

还可以添加一个 README 文件用于仓库说明。

推送源码仓库至 GitHub

这一步我使用 VS Code 完成，下面命令行代码供参考：

git add .
git commit -m "更新博客。"
git push origin main

查看网站

前往 GitHub，查看源码仓库是否已经与本地同步更新，然后检查 Action 执行情况，都无误的话，稍等 1 分钟左右，即可在 https://你的用户名.github.io 看到网站。

此后进行博客写作，只需将文章推送至源码仓库，GitHub Action 就会自动编译生成网站，并且自动部署到 GitHub Pages 上。

创建 GitHub 仓库#

安装 Hugo Extended#

配置 Hugo#

添加网站#

添加主题#

添加文章模板#

添加第一篇文章#

个性化配置#

配置 GitHub Action#

获取个人令牌#

添加令牌到仓库#

添加 Action 配置#

发布网站到 GitHub Pages#

添加 .gitignore 文件#

推送源码仓库至 GitHub#

查看网站#

参考文献#