小白写给小白。
1 安装 Hugo 和 Git
我在这里使用的是 Windows 11 操作系统。
1.1 安装 Hugo
Hugo是由Go编写的现代静态网站生成器，中文文档中提到 Git、Go、Dart Sass 是使用 Hugo 的先决条件。实际上，除了 Git，我们不需要特地安装 Go 和 Dart Sass。如果你不想部署，只想静静地欣赏自己的博客，连 Git 都可以省了。
Hugo有两个版本：标准版和扩展版。扩展版可以:
- 在处理图像时，将图像编码为WebP格式。无论您使用哪个版本，都可以解码WebP图像。
- 使用内置的LibSass转译器，将Sass转译为CSS。使用 Dart Sass 转译器时不需要扩展版。
看不懂，但看得出来扩展版包含了 Dart Sass 的功能。推荐使用扩展版，所以我们安装拓展版。
Hugo 有三种安装方式：包管理器、从源代码构建和预编译二进制文件。我们小白选择预编译二进制文件，全程窗口化操作，不需要打代码。
首先我们需要下载预编译二进制文件，进入 Hugo 的 release 页面，目前最新的版本是 v0.149.0，看到 Assets ，找到对应的文件，我使用的是 hugo_extended_0.149.0_windows-amd64.zip，下载。
之后，创建一个名为 Hugo 的文件夹，Hugo 文件夹中再创建 sites 和 bin 两个文件夹。我们将下载好的 .zip 文件解压 bin 文件夹中，打开 bin 文件夹，你可以看到有 hugo.exe ，复制好 hugo.exe 的文件路径，文件路径最好全为英文。现在我们把 Hugo 程序拷贝到了我们的电脑上，但是当我们想要使用 Hugo 时 Windows 系统不知道 Hugo 程序在哪，因此我们需要在 Windows 系统中指定 Hugo 文件的位置，即设置 Windows 系统的 PATH环境变量。
1📁 Hugo
2├── 📁 bin
3│ ├── 📄 hugo.exe
4│ ├── 📄 LICENSE
5│ └── 📄 README.md
6└── 📁 sites
7 └── 📁 MyBlog
打开 Windows 开始菜单，搜索 编辑系统环境变量，点击 环境变量，在上方的用户变量中找到变量名为 Path，选中它，再点击编辑，弹出窗口后，点击 新建，把我们上面复制的文件路径粘贴进去，一路点击确定。PATH 环境变量就设置好了，现在可以打开 cmd 或者 powershell 窗口，输入 Hugo version，出现 hugo v0.149.0 的信息就说明设置成功！
现在我们可以在 Windows 系统上的任何一个角落使用 Hugo 了。
1.2 安装 Git
Git 是一个开源的分布式版本控制系统，用于敏捷高效地处理任何或小或大的项目。在这里，我们利用这个系统将我们的网站上传到 Github 网站上，理论上只要能够访问到 github 就能够访问到我们的博客。
现在点击下载 Git, 下载好后直接双击运行 exe 文件。除了修改安装路径，剩下基本就是默认，具体的操作可以参考这篇文章。在开始菜单中看到Git的三个启动图标（Git Bash、Git CMD(Deprecated)、Git GUI）就说明安装好了。
2 安装及个性化 PaperMod 主题
我喜欢简洁大方的风格，这款 PaperMod 主题就很对我的口味。简约不失奢华，奢华中又有一丝认真，认真中又透着些许优雅，非常适合我这种敏感肌的宝宝使用。
2.1 建立博客并安装 PaperMod 主题
在之前，我们只是把 Hugo 和 Git 程序安装到了我们的电脑上，现在可以使用 Hugo 搭建一个基础的网站了。
打开 cmd 或者 powershell，使用 cd 命令进入到 Hugo 文件夹下的 sites 文件夹，使用
1hugo new site MyBlog
来创建一个名为 MyBlog 的站点。现在 cd 进入 MyBlog，你可以打开 MyBlog 文件夹直观地看到网站的目录结构。
1📁 MyBlog
2├── 📁 .git
3├── 📁 archetypes
4├── 📁 assets
5├── 📁 content
6├── 📁 layouts
7├── 📁 public
8├── 📁 static
9├── 📁 themes
10├── 📄 .gitmodules
11├── 📄 .hugo_build.lock
12└── 📄 hugo.yaml
注意到 content 文件夹了吗，它是文章的仓库，所有的文章都应该在这个文件夹里面。同样，在 MyBlog 文件夹下，你可以使用以下命令创建一篇文章
1# 在 content 文件夹下的 posts 文件夹下创建一篇名为 myfirstpost 的文章
2hugo new content/posts/myfirstpost.md
确保你在 MyBlog 文件夹下，我们需要运行 git 命令，使得 git 能够控制我们的网站项目。使用
1# 初始化 git ，告诉 git ，你可以控制 MyBlog 文件夹了
2git init
3
4#下载 PaperMod 主题，将下载的主题放到 themes 文件夹中的 PaperMod 文件夹下
5git submodule add https://github.com/adityatelange/hugo-PaperMod themes/PaperMod
现在我们下载好了 PaperMod 主题文件，需要应用 PaperMod 主题到我们的网站上。我们打开 MyBlog 文件夹，找到 hugo.toml 文件，最好将 toml 格式改为 yaml 格式。简单粗暴点，直接重命名，修改文件后缀名。现在双击打开 hugo.yaml，推荐 VS Code 软件 ，写上
1theme = PaperMod
现在我们就应用上了 PaperMod 主题。干唠了这么久我都累了，必须拿点硬货出来，打开 cmd 或者 powershell ，进入到 MyBlog 文件夹中，使用
1hugo server
运行我们的网站。确认正确运行后，打开 http://localhost:1313，就可以查看网站了。
我们可以边美化边运行网站，每当我们保存配置时，网站都会自动更新，非常有利于查看配置结果。摁下 Ctrl+C 来停止网站。
2.2 基本配置
我们需要对网站进行一些个人化的配置，包括网站的网址、名称等。这里给出的 yaml 代码是我目前的配置文件，可以按需添加和修改。
1# 网站的基础URL，用于生成绝对地址
2baseURL: "https://caiyu.life/"
3
4# 网站的标题
5title: "solren的网络自留地"
6
7# 使用的Hugo主题名称
8theme: PaperMod
9
10# 网站的主要语言代码
11languageCode: zh-cn
12
13# 启用CJK（中日韩）语言支持，优化中文排版和字数统计
14hasCJKLanguage: true
15
16# 启用生成robots.txt文件，帮助搜索引擎爬虫索引网站
17enableRobotsTXT: true
18
19# 不构建标记为草稿的文章
20buildDrafts: false
21
22# 不构建发布日期为未来的文章
23buildFuture: false
24
25# 不构建已过期的文章
26buildExpired: false
27
28# 启用表情符号支持
29enableEmoji: true
30
31# 网站的默认内容语言
32defaultContentLanguage: zh
33
34# 输出文件压缩配置
35minify:
36 # 禁用XML压缩
37 disableXML: true
38 # 启用输出压缩
39 minifyOutput: true
40
41# 多语言配置
42languages:
43 zh:
44 # 语言名称
45 languageName: "中文"
46 # 分类法配置
47 taxonomies:
48 category: categories # 分类使用的URL路径
49 tag: tags # 标签使用的URL路径
50
51# 输出格式配置
52outputs:
53 home:
54 - HTML # 生成HTML页面
55 - RSS # 生成RSS订阅
56 - JSON # 生成JSON文件，用于搜索引擎索引
57
58# 主题参数配置
59params:
60 # 主题模式: auto(自动), light(亮色), dark(暗色)
61 defaultTheme: light
62 # 显示文章导航链接
63 showPostNavLinks: true
64 # 启用代码高亮功能
65 enableHighlight: true
66
67 # 主要内容区域配置
68 mainSection:
69 - post # 文章所在的部分
70
71 # 日期显示格式
72 dateFormat: "2006年01月02日"
73
74 # 显示文章目录
75 ShowToc: true
76 # 默认展开文章目录
77 TocOpen: true
78 # 显示最后修改时间
79 ShowLastMod: true
80 # 显示阅读时间估算
81 ShowReadingTime: true
82
83 # 网站图标配置
84 assets:
85 favicon: "me.jpg" # 网站图标
86 favicon16x16: "me.jpg" # 16x16图标
87 favicon32x32: "me.jpg" # 32x32图标
88 apple_touch_icon: "me.jpg" # Apple设备触摸图标
89 safari_pinned_tab: "me.jpg" # Safari浏览器 pinned tab 图标
90
91 # 个人资料模式配置
92 profileMode:
93 enabled: true # 启用个人资料模式
94 title: "<Title>" # 个人资料标题，可选，默认为网站标题
95 subtitle: "我思故我在。" # 个人资料副标题
96 imageUrl: "me.png" # 个人资料图片
97 imageTitle: "I'm solren" # 图片标题
98 imageWidth: 150 # 图片宽度
99 imageHeight: 150 # 图片高度
100
101 # 个人资料下方的按钮配置
102 buttons:
103 - name: 文章 # 按钮名称
104 url: "/posts/" # 按钮链接
105 - name: 关于 # 按钮名称
106 url: "/about/" # 按钮链接
107
108 # 社交媒体图标配置
109 socialIcons:
110 - name: github # GitHub图标
111 url: "https://github.com/so1ren" # GitHub链接
112 - name: QQ # QQ图标
113 url: "qq.jpg" # QQ链接（可能是二维码图片）
114 - name: email # 邮箱图标
115 url: "mailto:caiyu2001@126.com" # 邮箱链接
116
117 # 搜索功能配置（使用Fuse.js）
118 fuseOpts:
119 isCaseSensitive: false # 是否大小写敏感
120 shouldSort: true # 是否对结果排序
121 location: 0 # 搜索位置参数
122 distance: 1000 # 搜索距离参数
123 threshold: 0.4 # 匹配阈值
124 minMatchCharLength: 0 # 最小匹配字符长度
125 keys: ["title", "permalink", "summary", "content"] # 搜索的字段
126 includeMatches: true # 是否包含匹配信息
127
128# 网站导航菜单配置
129menu:
130 main: # 主菜单
131 - identifier: tags # 菜单项标识符
132 name: 标签 # 菜单项显示名称
133 url: /tags/ # 菜单项链接
134 weight: 10 # 菜单项权重（决定显示顺序）
135 - identifier: archives
136 name: 归档
137 url: /archives/
138 weight: 20
139 - identifier: search
140 name: 搜索
141 url: /search/
142 weight: 30
143 - identifier: about
144 name: 关于
145 url: /about/
146 weight: 40
特别需要注意的是，图片需要放置在 /staic 目录下，将一些链接换成自己设置的就好。
2.3 个性化 PaperMod 主题
我们首先要知道，网站是由 HTML、CSS、JavaScript 构成的。如果把网站比作房子，那么
- HTML (超文本标记语言) - 房屋的结构：定义了哪里是标题 (
<h1>)、哪里是段落 (<p>)、哪里是图片 (<img>)、哪里是链接 (<a>)。 - CSS (层叠样式表) - 房屋的装修：控制所有 HTML 元素的样式，比如颜色、字体、大小、间距、布局、动画等。
- JavaScript (JS) - 房屋的电器和智能系统：让网页可以“动”起来，比如点击按钮弹出菜单、轮播图自动切换、动态加载内容等。
因此我们可以修改或编写上面的这些文件来个性化，主要围绕添加自定义 CSS 和 JS 文件。现在你可以自由地美化网站了，我在这里提到的任何美化或功能都只是示例，旨在抛砖引玉。符合自己的审美才是最好的个人博客。
强烈推荐 VS Code 软件用来管理和修改配置文件，使用 AI 辅助我们修改配置能够大大降低难度，减小工作量。甚至能够省去复制粘贴。
2.3.1 自定义字体
简洁的博客多是一些文字，字体的选择就变得很重要。我在这里使用霞鹜文楷屏幕阅读版作为中文字体，Arial 作为英文字体。
我们首先需要下载这款字体，点击霞鹜文楷屏幕阅读版下载 ttf 文件。中文字体文件通常很大，直接使用 ttf 文件可能会严重影响网站加载速度。我们需要将它转换为 woff2 格式，点击转化，上传 ttf 文件，下载转化后的 woff2 文件，放到 static\fonts\ 中，没有 fonts 文件夹就新建。
现在我们需要将下载的字体文件应用到网站。上面提到 CSS 文件主要控制样式，因此我们需要创建一个 CSS 文件。好在 PaperMod 主题帮我们创建好了 CSS 文件，位于 themes\PaperMod\assets\css\extended \blank.css ，按路径找到 blank.css，打开。在 blank.css 中加入
1/* 中文字体定义 */
2@font-face {
3 font-family:'LXGW';
4 src: url('/fonts/LXGWWenKaiMonoGBScreen.woff2') format('woff2');
5}
6
7/* 应用字体 */
8body {
9 font-family: Arial, 'LXGW', sans-serif;
10 font-size: 20px;
11 line-height: 1.8;
12 word-break: break-word;
13 background: var(--theme);
14 font-display: swap; /* 确保文本在字体加载时保持可见 */
15}
16
17/* 代码块保持等宽字体 */
18code, pre {
19 font-family: 'Fira Code', 'Source Code Pro', monospace;
20}
如果你使用其他的字体，只需要修改对应的 url。要注意的是，Arial 是自带的字体，不需要引入。我们先应用英文字体 Arial，再应用中文字体，这样可以保证中英文字体都是我们指定的。
2.3.2 自定义粗体颜色
为了文章更清楚简洁，我喜欢改变粗体的颜色。通过添加 CSS 很简单就可以实现，打开 blank.css 加入
1/* 自定义粗体颜色 */
2:root {
3 --bold-color-1: #ff1492;
4}
5
6.post-content strong {
7 color: var(--bold-color-1);
8}
你不必使用和我相同的颜色，通过修改 #ff1492，更换颜色。
2.3.3 优化目录
主题默认目录在文章上方，这样在阅读时就没办法快速跳转。我更喜欢把目录放在右边，因为鼠标也在右边，这样更符合人体的习惯。
我们需要修改页面的 HTML，PaperMod 主题的 single.html 负责生成博客中每一篇文章的页面，但是我们不能直接修改主题文件，因为一旦主题有更新，所有修改都会被覆盖丢失。正确的做法是在你的站点根目录创建同名文件进行覆盖。我们需要在 layouts\_default\single.html 中创建 single.html，现在找到 themes\PaperMod\layouts\_default\single.html，将这个 single.html 复制到 layouts\_default\ 文件夹中，没有文件夹就新建，之后提到的 single.html 默认是我们复制出来的文件。现在打开 single.html，加入
1</header>
2 {{- $isHidden := (.Param "cover.hiddenInSingle") | default (.Param "cover.hidden") | default false }}
3 {{- partial "cover.html" (dict "cxt" . "IsSingle" true "isHidden" $isHidden) }}
4
5 <!-- 新增：内容和目录包裹容器 -->
6 <div class="post-content-toc-wrapper" style="position:relative;">
7 {{- if .Content }}
8 <div class="post-content">
9 {{- if not (.Param "disableAnchoredHeadings") }}
10 {{- partial "anchored_headings.html" .Content -}}
11 {{- else }}{{ .Content }}{{ end }}
12 </div>
13 {{- end }}
14 {{- if (.Param "ShowToc") }}
15 <aside class="post-toc-float">
16 {{- partial "toc.html" . }}
17 </aside>
18 {{- end }}
19 </div>
20 <!-- 结束 -->
21
22 <footer class="post-footer">
23 {{- $tags := .Language.Params.Taxonomies.tag | default "tags" }}
24 <ul class="post-tags">
你只需要加入从 新增 到 结束中的代码，上方和下方的代码是为了告诉你加入代码的位置。
在文件末尾，{{- end }}{{/* end main */}} 前面加入
1<!-- 目录高亮脚本 -->
2<script>
3document.addEventListener('DOMContentLoaded', function () {
4 const tocLinks = document.querySelectorAll('.toc a[href^="#"]');
5 const headings = Array.from(tocLinks).map(link => {
6 const rawHref = link.getAttribute('href').replace('#', '');
7 const id = decodeURIComponent(rawHref);
8 return document.getElementById(id);
9 });
10 function onScroll() {
11 let activeIndex = -1;
12 for (let i = 0; i < headings.length; i++) {
13 if (headings[i] && headings[i].getBoundingClientRect().top - 100 < 0) {
14 activeIndex = i;
15 }
16 }
17
18 tocLinks.forEach((link, idx) => {
19 if (idx === activeIndex) {
20 link.classList.add('active');
21 } else {
22 link.classList.remove('active');
23 }
24 });
25 }
26 window.addEventListener('scroll', onScroll);
27 onScroll();
28});
29</script>
这段代码添加了目录高亮和滚动的功能。
现在你还需要在 blank.css 中加入
1.post-toc-float {
2 position: fixed !important;
3 top: 150px;
4 right: 45px;
5 width: 320px;
6 max-height: 200vh;
7 overflow-y: auto;
8 z-index: 999;
9 background: transparent;
10 box-shadow: none;
11 border-radius: 0;
12 padding: 0;
13}
14
15/* 目录固定右侧，内容留出空间 */
16@media (min-width: 1450px) {
17 .post-single {
18 margin-right: 10px !important; /* 留出目录宽度+间距 */
19 }
20 .post-toc-float {
21 display: block;
22 }
23}
24
25/* 小屏幕下隐藏目录 */
26@media (max-width: 1449px) {
27 .post-single {
28 margin-right: 0 !important;
29 }
30 .post-content-toc-wrapper {
31 display: flex;
32 flex-direction: column;
33 }
34
35 .post-toc-float {
36 display: block !important;
37 position: static !important;
38 width: auto;
39 max-height: none;
40 top: auto;
41 right: auto;
42 margin-bottom: 0px;
43 background: transparent;
44 box-shadow: none;
45 border-radius: 0;
46 padding: 0;
47 order: -1; /* 保证目录在内容前面 */
48 }
49}
50
51.toc a.active {
52 font-weight: bold;
53 color: var(--bold-color-1);
54}
这段代码保证了目录在文章内容的右边，同时，如果你是小屏幕打开，目录会自动调整到文章上方。
3 部署到 Cloudflare Pages
请确认你有一个 Github 账号、Cloudflare 账号，最好有一个域名并托管到 Cloudflare。
3.1 上传项目到 Github
现在我们需要将整个网站上传到 Github，在 Github 上新建一个仓库，可以是私人的，记住这个仓库的远程 URL。
如果没有初始化，可以在网站根目录树下打开 cmd 或 powershell 输入
1git init
初始化成功后，输入
1# 添加文件到暂存区
2git add
3
4# 提交更改到本地仓库
5git commit -m "提交信息"
6
7# 添加远程仓库地址，远程仓库地址为你在 github 平台上仓库的实际URL。
8git remote add origin 远程仓库地址
9
10# 将本地仓库推送到远程仓库
11git push -u origin main
到此，你就完成了对网站的更新。
如果你像我一样，将 PaperMod 主题作为一个子模块引入到网站中，你会发现对 PaperMod 主题文件的更改没有被包含在你这次推送的提交中。这是因为 PaperMod 主题文件本身就是一个独立的 Git 仓库，你需要先在子模块自己的仓库里进行提交和推送，然后再回到主项目里，更新主项目所“记录”的子模块版本号，最后再提交和推送主项目。第一步，我们先修改 PaperMod 主题的远程仓库地址，要把它关联到我们自己的 PaperMod 项目里，所以你最好 fork PaperMod 到自己的仓库，记下这个仓库的远程地址。在网站根目录打开终端，输入
1# 进入子模块目录
2cd themes/PaperMod
3
4# 更改远程仓库地址（替换为你的用户名和仓库名）
5git remote set-url origin https://github.com/YOUR_USERNAME/YOUR_PAPERMOD_FORK.git
6
7# 验证更改
8git remote -v
更改子模块的远程地址后，你需要更新主项目中的子模块引用，接着输入
1# 回到主项目根目录
2cd ../..
3
4# 更新子模块配置
5git submodule sync
6
7# 添加更改到暂存区
8git add .gitmodules
9
10# 提交更改
11git commit -m "更新子模块远程仓库地址"
现在，我们每次美化完网站，需要先提交子模块 PaperMod 主题到远程仓库，再在主项目提交修改。你需要先运行
1git submodule update --remote themes/PaperMod
然后，就可以正常地提交主项目了。
如果你想我一样，只是一个小白，不想每次提交都打这么多命令，有没有办法每次提交都只打一个命令？
当然是有，我们可以创建一个自定义 git 命令，把我们需要的命令全都囊括进去。记得我们安装 Git 时，开始栏出现的 Git bash 程序吗，现在打开它，输入
1git config --global alias.publish '!f() { \
2 echo ">>> 开始发布流程..."; \
3 \
4 # 检查子模块 \
5 if [ -d "themes/PaperMod" ] && [ -f "themes/PaperMod/.git" ]; then \
6 echo ">>> 处理 PaperMod 子模块..."; \
7 \
8 # 进入子模块目录 \
9 cd themes/PaperMod; \
10 \
11 # 检查子模块是否有更改 \
12 if [ -n "$(git status --porcelain)" ]; then \
13 echo ">>> 子模块有未提交的更改，正在提交..."; \
14 git add .; \
15 git commit -m "PaperMod更新: $1"; \
16 else \
17 echo ">>> 子模块无未提交的更改"; \
18 fi; \
19 \
20 # 尝试推送子模块 \
21 if git push origin main 2>/dev/null; then \
22 echo ">>> 子模块推送成功"; \
23 else \
24 echo ">>> 子模块推送失败，但提交已创建"; \
25 echo ">>> 提示: 请确保你有权限推送到子模块远程仓库"; \
26 fi; \
27 \
28 # 返回主项目目录 \
29 cd ../..; \
30 \
31 # 更新主项目中的子模块引用 \
32 git add themes/PaperMod; \
33 echo ">>> 已更新主项目中的子模块引用"; \
34 else \
35 echo ">>> 未找到 PaperMod 子模块，跳过子模块处理"; \
36 fi; \
37 \
38 # 检查主项目是否有更改 \
39 if [ -n "$(git status --porcelain)" ]; then \
40 echo ">>> 提交主项目更改..."; \
41 git add .; \
42 git commit -m "$1"; \
43 \
44 # 推送主项目 \
45 if git push origin main; then \
46 echo ">>> 主项目推送成功"; \
47 else \
48 echo ">>> 主项目推送失败"; \
49 fi; \
50 else \
51 echo ">>> 主项目无更改，跳过提交"; \
52 fi; \
53 \
54 echo "✅ 发布流程完成!"; \
55}; f'
注意，所有的仓库统一使用 main 分支，你需要统一所有仓库的默认分支。如果你看得懂上面的代码的话，也可以基于你的仓库分支修改代码。
现在，在你的网站根目录打开终端，运行
1git publish "你的提交信息"
就可以提交所有更改到远程仓库了。这个命令会依次执行：
- 检查并提交子模块的更改
- 尝试推送子模块到远程仓库
- 更新主项目中的子模块引用
- 提交并推送主项目的所有更改
如果子模块推送失败，它会继续执行主项目的提交和推送，确保我们的工作不会丢失。
3.2 提交网站到 Cloudflare Pages
过程非常简单，你可以参考这篇文章。
4 写在最后
用一句话概括物理学家费曼的学习方法：用教给别人听的方式，来发现自己哪里没学懂。
在写这篇文章前，我只是笨拙地复制粘贴代码，按教程做一个流水线工人，批量地复制出相同的网站。通过一点点地拼凑出这篇文章，才知道原来我做了这么多，懂得的却这么少，也对个人博客有更深的理解，实在受益匪浅。
希望这篇文章对你也有所帮助！
5 附录
5.1 VS Code
通过 VS Code 和人工智能的帮助，我们可以很轻松地个性化自己的网站。
点击这里来下载 VS Code，这篇文章可以指导你正确安装并配置。
VS code 和人工智能结合是我们小白的大救星，这里有一篇文章可以指导你学会在 VS Code 中使用 DeepSeek。
5.2 参考文献
- Hugo 官方文档
- PaperMod 官方文档
- 国产大模型 Deepseek 这就是本篇的全部内容。如果觉得有收获，可以分享给需要的朋友。
