用 hugo 搭建博客（一）- 搭建与部署

用 hugo 来搭建一个博客网站，使用 PaperMod 作为主题，部署到 GitHub Pages

hugo

Quick start

按照 Quick start 中的步骤安装好 hugo 之后，便可以创建一个 blog 项目，默认的配置文件是hugo.toml，创建时使用--format可以指定为其他格式，比如yaml

1
hugo new site blog --format yaml

创建好的 blog 项目是没有被 git 管理的，可以在 blog 目录中git init一下，然后就可以安装主题了

PaperMod

wiki

使用 wiki 中 Installation 章节推荐的方法来安装主题

1
2
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)

然后在 hugo 的配置文件（这里是hugo.yaml）中添加配置

1
theme: ["PaperMod"]

现在就可以用hugo server命令启动服务，访问 http://localhost:1313/ 来查看网站了

文章

使用下面的命令可以新增一篇文章，文章默认会被放在content目录下，如果是类似于posts/test.md的写法，就是在content/posts目录，这样可以把文章和之后要添加的archives.md、search.md等页面分开，好管理一些

1
hugo new content posts/test.md

默认情况下，新增文章的头信息（front matter）会是tomal语法，可以修改archetypes/default.md来修改模板，比如改成yaml格式

1
2
3
4
5
---
title: '{{ replace .File.ContentBaseName "-" " " | title }}'
date: {{ .Date }}
draft: true
---

配置

存档和搜索页面

这两个页面需要在content目录中添加对应的 md 文件，如：

archives.md

1
2
3
4
5
6
---
title: "Archive"
layout: "archives"
url: "/archives/"
summary: archives
---

search.md

1
2
3
4
5
6
---
title: "Search"
layout: "search"
summary: "search"
placeholder: "placeholder text in search input box"
---

然后在hugo.yaml中配置菜单，类似于下面这样，url 要和 md 文件名一致

1
2
3
4
5
6
7
8
menu:
  main:
    - name: Archives
      url: /archives/
      weight: 10
    - name: Search
      url: /search/
      weight: 20

分类

修改hugo.yaml，在taxonomies 中指定默认的标签tag、分类category和自定义的series三种分类方法，详细内容可以参考Taxonomies

1
2
3
4
5
# 分类
taxonomies:
  tag: tags
  category: categories
  series: series

之后添加三种分类方法对应的菜单，用weight来指定菜单的顺序

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
menu:
  main:
    - name: Archives
      url: /archives/
      weight: 20
    - name: Categories
      url: /categories/
      weight: 30
    - name: Tags
      url: /tags/
      weight: 40
    - name: Series
      url: /series/
      weight: 50
    - name: Search
      url: /search/
      weight: 60

在文章的头信息中指定对应的分类，如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
---
title: '用 hugo 搭建博客'
date: 2024-07-09T09:01:51+08:00
draft: true
categories:
  - tech
tags:
  - blog
series:
  - blog
---

更多配置

  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
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
# url
baseURL: https://thmaster.net
# 语言
languageCode: zh
# 标题
title: th-master
# 主题
theme: "PaperMod"

# 一页文章数
paginate: 5

# 分类方法
taxonomies:
  # 标签
  tag: tags
  # 分类
  category: categories
  # 系列
  series: series

# 菜单
menu:
  main:
    - name: 归档
      url: /archives/
      weight: 20
    - name: 技术
      url: /categories/tech/
      weight: 21
    - name: 生活
      url: /categories/life/
      weight: 22
    - name: fun
      url: /categories/fun/
      weight: 23
    - name: 分类
      url: /categories/
      weight: 30
    - name: 标签
      url: /tags/
      weight: 40
    - name: 系列
      url: /series/
      weight: 50
    - name: 搜索
      url: /search/
      weight: 60

# 启用 emoji，可以使用 :cry: 的语法显示 emoji
# 详情见 https://gohugo.io/getting-started/configuration/#enableemoji
enableEmoji: true
# 内联短码，详情见 https://gohugo.io/templates/shortcode/#inline-shortcodes
enableInlineShortcodes: true
# 生成 robots.txt
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
# 代码高亮中使用 css class 来指定样式
pygmentsUseClasses: true
# 自动检测内容中的中文/日文/韩文，确保词数统计等功能正常
# 详情见https://gohugo.io/getting-started/configuration/#hascjklanguage
hasCJKLanguage: true

outputs:
  home:
    - HTML
    - RSS
    - JSON # necessary for search

params:
  env: production
  description: "th-master's blog"
  # 作者
  author: th-master
  # 日期格式化
  DateFormat: "2006-01-02"
  # 默认主题
  defaultTheme: dark
  # 阅读用时
  ShowReadingTime: true
  # 上一篇/下一篇 导航链接
  ShowPostNavLinks: true
  # 面包屑导航
  ShowBreadCrumbs: true
  # 代码块复制按钮
  ShowCodeCopyButtons: true
  # 在存档页面中显示所有页面
  ShowAllPagesInArchive: true
  # 显示分页
  ShowPageNums: true
  # 显示字数统计
  ShowWordCount: true
  # 显示目录
  ShowToc: true
  # 默认展开目录
  TocOpen: true

  # 主页
  homeInfoParams:
    Title: "Hi :innocent:"
    Content: Welcome to my blog

  # 社交链接
  socialIcons:
    - name: github
      title: "Github"
      url: "https://github.com/"

  assets:
    # 不加载代码高亮库
    disableHLJS: true

markup:
  goldmark:
    renderer:
      # 允许在 md 中使用不安全的 HTML 标签
      unsafe: true
  # 代码高亮
  highlight:
    # 使用 css class 来指定代码高亮的样式
    noClasses: false
    # 启用代码高亮
    codeFences: true
    # 没有指定语言时猜测代码的语言并应用对应的高亮
    guessSyntax: true
    # 代码块显示行号
    lineNos: true
    # 代码高亮的样式主题
    style: monokai

GitHub Pages

部署

Host on GitHub Pages
关于 GitHub Pages

直接参考上面的两篇文档，创建一个名为<user>.github.io的仓库，将本地的 blog 项目推送上去

然后在 GitHub 仓库页面选择 Settings > Pages，将 Build and deployment > Source 选项从Deploy from a branch修改为GitHub Actions

之后在本地仓库中创建.github/workflows/hugo.yaml文件，将Host on GitHub Pages中提供的内容粘贴进去，视情况修改其中的分支名称，比如从main改为master

提交此修改并推送至 GitHub

之后在每次推送时，都会产生一个 workflow 进行构建和部署，在 Actions 页面可以查看，待 workflow 成功结束之后就可以用<user>.github.io来访问了

自定义域名

文档中的建议是给顶级域名和 www 二级域名都配置上 DNS，然后自定义域名设置为 www 二级域名，这样访问顶级域名时会自动跳转到 www 二级域名

参考文档建议，修改自己域名的 DNS，给根域名和 www 添加 CNAME 类型的记录，内容为<user>.github.io

然后回到 GitHub 仓库的 Settings > Pages 设置，在 Custom domain 下填入域名如www.xxx.com，点击 Save 保存，等待 DNS 检查完毕之后，就可以用自定义域名来访问了

hugo#

PaperMod#

文章#

配置#

存档和搜索页面#

分类#

更多配置#

GitHub Pages#

部署#

自定义域名#