Hugo Github Pages 自建博客教程

前言

自己尝试通过Hugo这个静态网站生成器来搭建我的个人博客，踩了很多坑，现在把自己的历程写一下。

现在已经实现的是一下几个部分：

个人博客源仓库，对自己的博客的配置以及所有文章进行版本管理
GitHub Pages 博客仓库发布，以username.github.io进行查看，可以自定义域名
通过GitHub Action将个人博客源仓库自动发布到GithubPages仓库中

使用Hugo搭建博客

安装Hugo

Hugo版本：标准版和扩展版。其中扩展版本的优势是（借用官方的文字，实际上没太看明白）：

Encode to the WebP format when processing images. You can decode WebP images with either edition.
Transpile Sass to CSS using the embedded LibSass transpiler. The extended edition is not required to use the Dart Sass transpiler.

下载Hugo 官方推荐的是扩展版本，扩展版下载地址Releases · gohugoio/hugo (github.com)
解压到合适的目录
设置系统变量
打开终端输入
1
hugo version
出现如下图表示安装成功

创建Hugo网站

安装完Hugo程序后，就可以通过命令hugo new site命令进行网站的创建、配置和本地调试了

1
hugo new site Blog

出现下图的提示，表示创建成功。同时会在生成一个Blog的文件夹

Blog文件夹的内容

1
2
3
4
5
6
7
8
9
.
├── archetypes: default.md是生成博文的模版
├── assets # 存放被 Hugo Pipes 处理的文件
├── content # 存放markdown文件作为博文内容
├── data # 存放 Hugo 处理的数据
├── layouts # 存放布局文件
├── static # 存放静态文件 图片 CSS JS文件
├── themes: 存放不同的主题
└── hugo.toml: 博客配置文件支持 JSON YAML TOML 三种格式配置文件

注意：后续没有特别的说明，所有操作都在Blog文件夹下操作。

配置主题

安装主题

主题有非常多，可以从Github上搜索。我最开始用的是dillonzq/LoveIt: ❤️A clean, elegant but advanced blog theme for Hugo 一个简洁、优雅且高效的 Hugo 主题 (github.com)这个主题。主题的文档在LoveIt (hugoloveit.com)

把主题直接克隆到themes目录：

1
git clone https://github.com/dillonzq/LoveIt.git themes/LoveIt

当然也可以初始化Blog为项目目录，主题仓库作为网站目录的子模块，我本人没用这种方式，请自行研究

1
2
git init
git submodule add https://github.com/dillonzq/LoveIt.git themes/LoveIt

基础配置

一下是LoveIt的基础配置，将此配置覆盖到Blog跟目录的huto.toml

 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
baseURL = "http://example.org/"

# 更改使用 Hugo 构建网站时使用的默认主题
theme = "LoveIt"

# 网站标题
title = "我的全新 Hugo 网站"

# 网站语言, 仅在这里 CN 大写 ["en", "zh-CN", "fr", "pl", ...]
languageCode = "zh-CN"
# 语言名称 ["English", "简体中文", "Français", "Polski", ...]
languageName = "简体中文"
# 是否包括中日韩文字
hasCJKLanguage = true

# 作者配置
[author]
  name = "xxxx"
  email = ""
  link = ""

# 菜单配置
[menu]
  [[menu.main]]
    weight = 1
    identifier = "posts"
    # 你可以在名称 (允许 HTML 格式) 之前添加其他信息, 例如图标
    pre = ""
    # 你可以在名称 (允许 HTML 格式) 之后添加其他信息, 例如图标
    post = ""
    name = "文章"
    url = "/posts/"
    # 当你将鼠标悬停在此菜单链接上时, 将显示的标题
    title = ""
  [[menu.main]]
    weight = 2
    identifier = "tags"
    pre = ""
    post = ""
    name = "标签"
    url = "/tags/"
    title = ""
  [[menu.main]]
    weight = 3
    identifier = "categories"
    pre = ""
    post = ""
    name = "分类"
    url = "/categories/"
    title = ""

# Hugo 解析文档的配置
[markup]
  # 语法高亮设置 (https://gohugo.io/content-management/syntax-highlighting)
  [markup.highlight]
    # false 是必要的设置 (https://github.com/dillonzq/LoveIt/issues/158)
    noClasses = false

这时候运行一下命令

1
hugo server

打开网页：http://localhost:1313/可以看到网页了，网页如下

写第一篇文章

一下是创建第一篇文章的办法

1
hugo new posts/2024/09/061/index.md

为了博客记录，以及后期静态图片的位置存放问题，个人习惯将博文按照年、月、日的文件夹层级显示。一般日后面会加以为，个人一天之后写好多篇博文的可能性几乎为0，当然也可以根据自己的习惯进行处理。

打开index.md，文章模板如下

1
2
3
title = '071'
date = 2024-09-07T14:46:38+08:00
draft = true

根据自己的情况写一篇博文，然后将draft = true 改为 draft = false。不然页面不会显示。

本地调试

运行

1
hugo server	

这时候网页就可以显示你刚刚创作的文章了。

hugo是支持实时渲染的，当文章编辑保存后，网页会自动显示出效果