Blog on 苏三有春的博客

Hugo 博客维护踩坑记：主题迁移、暗色模式与 SCSS 优先级

Fri, 29 May 2026 12:00:00 +0800

为什么要用 Git Submodule

最初搭建博客时，我把 Hugo Theme Stack 的所有文件直接复制、提交到了博客仓库里。主题文件成百上千，和自己的文章、配置搅在一起。这带来几个问题：

无法追踪上游更新：上游修了 bug、加了新功能，我完全不知道，知道了也没法一键合并。唯一的选择是手动下载新版本的主题，重新覆盖，然后祈祷不要把自己改过的地方冲掉。
提交历史被污染：几百个主题文件的增删改和自己的博客文章混在同一个 git log 里，一眼看去完全分不清哪些是自己的创作、哪些是第三方代码。
仓库臃肿：主题文件占了大头，真正属于我的内容反而被淹没了。

Git Submodule 是什么

Git Submodule 允许一个 Git 仓库（主仓库）引用另一个 Git 仓库（子模块）的特定 commit，而不是把它的文件复制过来。

可以这样理解：不用 submodule 时，你等于把别人的房子拆了，砖头一块块搬到自己院子里重新盖；用了 submodule，你只是在自家院子里插了一块路牌，写着「去那边那个房子」。

关键特性：

主仓库只记录一个指针（子模块的 repo URL + commit hash），不存储子模块的实际文件
git clone 主仓库后，子模块目录是空的，需要 git submodule update --init 才会把子模块拉下来
子模块有自己独立的 .git 目录、独立的 commit 历史、独立的 remote
子模块的版本是精确锁定的——它指向一个具体 commit，不会自动更新

Submodule 的实际优势

	直接嵌入主题	Git Submodule
查看改动	`git diff` 里几百个主题文件混在一起	`git diff` 只显示指针 commit 的变化
更新主题	手动下载、覆盖、手动合并	`cd themes/xxx && git pull`
上游修复	不知道、合并痛苦	`git fetch origin && git merge`
回滚	混在博客历史中难以定位	主仓库 `git checkout` 一个旧 commit 即可恢复当时引用的主题版本
定制	直接改文件	通过 Hugo 的覆盖机制（`layouts/`、`assets/`、`static/`）在不碰主题源码的前提下定制

背景

基于以上原因，我决定把主题改成 git submodule 管理。但过程并不顺利，踩了四个坑，逐一记录。

第一步：把嵌入的主题改成 submodule + fork

思路很清晰：

Fork 一份 CaiJimmy/hugo-theme-stack 到自己的 GitHub
在 fork 里改好暗色模式的颜色（背景 #000000，卡片 #121317）
博客主仓库 git rm -r themes/hugo-theme-stack
git submodule add 指向上一步的 fork

这一步还算顺利。具体改动见 commit 52b389e。

坑一：submodule 指向的是 fork 的 v4.x，和博客用的 v3.9.x 不兼容

我的 fork 克隆的是上游 main 分支（v4.x），但博客一直用的是 v3.9.x。两个版本的目录结构、CSS 变量、模板写法都不一样。

现象：切 submodule 后，暗色模式的颜色没了，整体布局也有些差异。

最初的想法：切回 fork 的 v3.9.2 tag。但 fork 是直接从上游 fork 的 main，在 GitHub 上没法直接指定 fork 时的分支。

最终方案：submodule 直接指向上游 CaiJimmy/hugo-theme-stack 的 v3.9.2 tag，不要再维护一个 fork 了。主题定制统一通过 Hugo 的覆盖机制实现，不动主题源码。

1
2
3
4


# 切换 submodule
git checkout -- .gitmodules
git submodule add --force https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack
cd themes/hugo-theme-stack && git checkout v3.9.2 && cd ../..

--force 是因为 .git/modules/themes/ 里还缓存着旧的 git 目录。不加 --force 会报 A git directory for 'themes/hugo-theme-stack' is found locally。

坑二：Hugo v0.152.2 废弃 API，直接编译失败

GitHub Actions 用的 Hugo 版本是 0.152.2。在这个版本中：

resources.ToCSS → 已移除，需用 css.Sass
.Site.LastChange → 已移除，需用 .Site.Lastmod

但 hugo-theme-stack v3.9.2 仍然在用这些废弃 API。Workflow 直接报错退出。

解决方案：Hugo 布局文件的优先级是「项目 layouts/ > 主题 layouts/」。因此直接照搬主题中的三个文件到项目目录，修改一行即可：

文件	修改
`layouts/partials/head/style.html`	`resources.ToCSS` → `css.Sass`
`layouts/partials/comments/provider/disqusjs.html`	`resources.ToCSS` → `css.Sass`
`layouts/partials/head/opengraph/provider/base.html`	`.Site.LastChange` → `.Site.Lastmod`

1
2


-{{ $style := $sass | resources.ToCSS | minify | resources.Fingerprint "sha256" }}
+{{ $style := $sass | css.Sass | minify | resources.Fingerprint "sha256" }}

1
2


-{{- if not .Site.LastChange.IsZero -}}
+{{- if not .Site.Lastmod.IsZero -}}

坑三：`assets/scss/custom.scss` 暗色模式覆盖不生效（重点）

编译通过了，但暗色模式还是默认的 #303030 / #424242。

排查过程：我在项目根目录创建了 assets/scss/custom.scss，写入：

1
2
3
4


[data-scheme="dark"] {
 --body-background: #000000;
 --card-background: #121317;
}

主题的 assets/scss/style.scss 末尾有 @import "custom.scss"，理论上 Hugo 应该优先加载项目的 assets/scss/custom.scss。

但实际情况是：主题的 assets/scss/ 目录下也有一个 custom.scss，虽然它只是一个空注释：

1

/* Place your custom SCSS in HUGO_SITE_FOLDER/assets/scss/custom.scss */

Hugo 的 SCSS @import 解析器在遇到 @import "custom.scss" 时，会先在当前文件所在目录查找（即主题的 assets/scss/）。它找到了主题的那个空文件，加载了它，就停了。项目里的同名文件根本没被看到。

踩坑记录：

❌ 尝试覆盖 style.scss，把 @import "custom.scss" 改成 @import "site-custom.scss"，然后创建 site-custom.scss。这个方案理论上可行，但实际操作中因为之前的编译产物一致（都是默认色），GitHub Actions 的部署环节 peaceiris/actions-gh-pages 检测到 nothing to commit，跳过了部署，导致没有生效。
❌ 尝试直接修改 submodule 内的主题文件 —— 本地能跑，但 CI 重新 clone 子模块后又还原了。
✅ 最终方案：直接覆盖 assets/scss/variables.scss。

Hugo 的资源查找（resources.Get）逻辑和 SCSS @import 解析逻辑不同。resources.Get 会优先使用项目中的文件而不是主题中的。所以只要创建一个包含暗色模式的 assets/scss/variables.scss，Hugo 就会用它代替主题的版本。

1
2
3
4
5
6


# 拷贝主题的 variables.scss 到项目
cp themes/hugo-theme-stack/assets/scss/variables.scss assets/scss/variables.scss

# 修改暗色模式部分
# --body-background: #303030 → #000000
# --card-background: #424242 → #121317

这个方案不仅解决了 @import 优先级问题，而且改动集中在一个文件里，不依赖 custom.scss 的加载顺序。

坑四：部署日志显示成功，但 `.github.io` 仓库没更新

Workflow 日志里 Deploy Web 步骤显示：

1
2
3
4


git commit -m auto deploy ...
On branch main
nothing to commit, working tree clean
[INFO] skip commit

原因：peaceiris/actions-gh-pages@v4 默认行为会在目标仓库克隆一份，git rm -r * 清空，再 cp 新的构建产物进去，然后 commit。如果新的产物和上次完全一致（文件树 hash 相同），git 会认为没有变化，跳过 commit。

这发生在上一个坑的排查中 — 我们的 style.scss 覆盖方案编译出来的结果和默认主题一样（都是 #303030 / #424242），所以部署被跳过了。

只要修复真正生效（编译出不同的 CSS），部署就会重新触发。

总结：Hugo 主题定制的优先级规则

场景	Hugo 的行为	推荐做法
布局覆盖 (layouts/)	项目的 `layouts/` 优先于主题	直接复制主题文件到项目，修改
SCSS @import	先从导入文件的目录查找	不要和主题的同名文件冲突，避免用通用的名字如 `custom.scss`
resources.Get + SCSS	项目的 `assets/` 优先于主题	覆盖 `variables.scss` 是最可靠的
静态资源 (static/)	项目的 `static/` 覆盖主题同名文件	放 `static/img/avatar.png` 等

关键教训：在 Hugo 中给主题改样式，特别是改 CSS 变量，最稳妥的方式永远是 直接在项目中放置 assets/scss/variables.scss，而不是依赖 custom.scss 的 @import 机制。

附：本次改动总览

1
2
3
4
5
6
7


ff7709a switch theme submodule to upstream v3.9.2
d25696a move particles.js to head/custom.html
54a32e0 add dark mode overrides via custom.scss ← 没生效
60fd094 fix deprecated Hugo APIs (ToCSS, LastChange)
a03c80b override style.scss → site-custom.scss ← 编译成功但部署被跳过
84e15c4 trigger rebuild ← 同上
6c366ed fix: override variables.scss directly ← 最终生效 ✅

基于Hugo构建一个属于自己的博客（二）

Wed, 20 Nov 2024 21:48:00 +0800

前言

首先，想要实现这个功能的小伙伴需要完成几个前置条件：

有一个GitHub账号
安装了git，并可以通过git推送commit到GitHub上
完成第一篇文章的博客搭建

创建仓库

在GitHub上创建一个仓库，用来存放代码

如果你不是GitHub重度使用者或高手，建议你的仓库名称就是你自己的用户名 + .github + .io。如图所示：

这是因为，如果使用这个名字的话，那么在后续使用GitHub pages生成静态网站的域名就直接是你的仓库名，而不需要加其它后缀，可能会导致未知的bug

仓库必须公有，只有公有仓库才能部署静态页面

修改配置

还记得上一篇文章提到的，配置文件中有一个参数是讲url重定向到自己的GitHub仓库的吗，现在我们在创建自己的仓库之后，可以开始填写，修改hugo.yaml的`baseurl

1

baseurl: https://Lyrical-wander.github.io # 这里是我的仓库名称，如果你按照上面的步骤走，输入：https://用户名.github.io 即可

上传代码

上传代码前，首先查看你的站点目录下有没有public目录

这个public目录是生成的静态网站的代码，还记得我们上一个文章中使用的一条命令吗
1
hugo server -D
这条命令会启动hugo程序，将源码进行“编译”（当然并不是真正意义上的编译），生成html，scss等前端代码，这些代码构成静态网站。

如果没有生成public目录，那么就使用hugo server -D命令生成一下。

值得注意的是，如果你习惯用VScode中的git插件，也许会方便很多。但第一次上传代码也需要手敲命令

但幸运的是，当你第一次创建仓库，仓库中一无所有时，会提示你如何上传代码

在站点目录下启用cmd命令，逐条输入命令：

1
2
3
4
5
6


git init # 初始化git
git add . # 通过git上传当前目录下所有的文件
git commit -m "这是我的博客第一次提交" # 这里是给这一次提交写一个记录，说明这个提交是做什么的
git branch -M main # 创建主分支
git remote add origin xxxxxxxxx # 你是什么就填什么，不做修改
git push -u origin main

如果这里出问题，push不到仓库中，不是hugo或者stack的问题，请检查git与GitHub是否正常运行，以下有几个排查的方向：

网络问题，因为GitHub是全球服务器，因此国内访问可能会有些慢，有条件的同学开个代理
git并没有权限访问GitHub，看你是如何配置GitHub的，建议采用SSH，网上有许多git生成ssh密钥，GitHub绑定密钥的教程，建议跟着走一遍，如果采用HTTPS的话，应该是要登陆的，具体流程笔者很久没用了，也是建议上网搜索，网上教程很多

启用pages功能

如果你成功上传代码，现在可以打开GitHub上自动生成静态网页的pages功能，来帮你生成静态网页，等静态网页生成后，以后通过访问你的仓库域名，即可直接打开你的博客

进入你的仓库
在仓库菜单栏中找到Settings功能
在侧边菜单栏中找到Pages
在分支Branch中选择主分支main
保存Save

做完以上操作，等待一段时间静态网站部署，可能几分钟，刷新一下出现⑥处，则说明生成成功，访问这个域名即可访问你的博客！

值得注意的是，这里我是购买了自己的域名，然后解析到我的仓库，所以我的域名是www.lyrical-wander.cn，而不是www.lyrical-wander.github.io，而如果按照上面的步骤走的话，域名应该是：www.usename.github.io

至此，你的博客已经部署好了！可以开始访问你自己的博客啦

小结

还有需要注意的是：

每一次写完博客，都需要重新使用hugo server -D命令，生成新的public目录，push上GitHub
每次生成新的public，都会有大量的文件被改动，push起来非常不方便

因此我们要通过GitHub的Action功能来实现自动化部署

自动化部署

创建仓库

同样地，按照上面的步骤，我们重新创建一个仓库，这个仓库不会生成pages，且可以设置为私有仓库，因此随意命名，比如：hugo-main

修改代码

创建.gitignore文件

我们添加一个小文件，来保持我们代码的干净整洁。

因为每一次hugo server -D都会生成新的public和resources，而这个并不是我们编写的代码，因此这个可以忽略掉。

在站点目录下增加一个新文件.gitignore

填写以下内容：

这个文件顾名思义，可以让git忽略掉它里面填写的这些文件，这些文件git不会再检查它们的修改，也不会让你提交它们。

生成token并创建yaml配置文件

首先我们先生成一个token，获取该token，以免你以后每次上传代码都需要重新登录一遍

进入Settings

移动到最下方找到Developer settings

然后选择Personal access tokens→Tokens(classic)→Generate new token→Generate new token(classic)

生成token时可以将Expiration选择No expiration，即这个token永不过期。

下面Select scopes（作用范围）选择repo与workflow

后面就生成了token~

注意！这个token只会出现一次，之后再也不会出现，在你关闭网页前先复制保存！

回到你刚刚创建的 第二个仓库 上（我们称之为hugo主仓库吧），不是username.github.io那个仓库！

在仓库中打开Settings→Secrets and Variables→New repository secret 来创建一个存储token的变量

为什么要这么做呢，因为token这个东西比较重要，如果后续我们直接将它写到文件中，如果文件被窃取，那么token就会暴露，这样你的仓库就不安全了，尤其我们的token还选择了不过期。

因此，我们将token保存在GitHub中，以变量的形式传给我们的文件，这样token的密封性就很好了

回到我们的站点目录下，创建一个.github目录，在.github目录下创建一个workflows目录，在该目录下生成一个xxxxx.yaml文件，名字随便取

在xxxx.yaml文件下写入以下代码

 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


name: deploy

# 代码提交到main分支时触发github action
on:
 push:
 branches:
 - main

jobs:
 deploy:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout
 uses: actions/checkout@v4
 with:
 fetch-depth: 0

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

 - name: Build Web
 run: hugo -D

 - name: Deploy Web
 uses: peaceiris/actions-gh-pages@v4
 with:
 PERSONAL_TOKEN: ${{ secrets.你的token变量名 }} # 刚刚在上面创建的变量名
 EXTERNAL_REPOSITORY: 你的github名/你的仓库名 # 如果按照上面的步骤走，则是username/username.github.io第一个仓库名
 PUBLISH_BRANCH: main
 PUBLISH_DIR: ./public
 commit_message: auto deploy

上传代码

同样地，我们将站点代码再一次上传到这个仓库上，git操作一模一样，按照上面的上传代码部分来重新操作一遍即可。

1
2
3
4
5
6


git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin xxxxxxxxxxx
git push -u origin main

至此，你就实现了自动部署，现在，你撰写博文，然后直接push到第二个仓库，不需要本地生成public，就可以啦，第二个仓库会做一系列操作，并生成静态网站所需的资源和public，传到第一个仓库中，然后生成静态网站。

基于Hugo构建一个属于自己的博客（一）

Tue, 19 Nov 2024 21:47:00 +0800

前言

我想有一个地方，能够分享一些个人生活，记录一些技术知识，那么在茫茫大的网络世界中，有许多网站或者应用可以满足我的需求，比如CSDN，比如博客园，比如QQ空间（已经渐渐消失在时间的长河中了……）。但，总感觉差了些什么，它们既不能满足我的个人世界的全部想象，又不够极客主义，谁在小时候没有幻想过拥有一间完全由自己建造的，不受地皮，户型限制的房子呢？

因此，我决定开始搭建自己的个人博客，它将成为我在网络世界的一座小屋，它的风格，样式由我定义，它将随我漂流，我可以自由地为它添砖加瓦，也可以任性地删除任何我不满意的功能，也许在某天它将因为我的离开而荒废，但这里，有我在网络世界的一部分记忆，一部分独属于我的记忆……

笔者的个人博客，苏三有春的博客，采用了Hugo框架下的stack主题搭建，非常快速且简单（当然在搭建的过程当中笔者也踩了一些坑），因此写一篇博客来记录自己的搭建心得以及给有想法搭建个人博客的小伙伴们一些参考。

参考视频：

【雷】Hugo + Github免费搭建博客，并实现自动化部署_哔哩哔哩_bilibili

Hugo

Hugo是由Go语言实现的静态网站生成器。简单、易用、高效、易扩展、快速部署，可以帮助用户快速构建高性能的静态网站，方便个人搭建博客，和个人网站等。Hugo在GitHub（ The world’s fastest framework for building websites.）上拥有超过75K stars，近千名贡献者，拥有活跃的社区，保证了Hugo成为当下最流行的静态网站生成器之一，正如其标题所说：“Hugo是世界上最快的构建网站的框架”。

Hugo下载

Hugo框架的下载有一些注意事项：

Hugo根据操作系统的不同有不同的下载方式

MacOS

brew install hug

Linux

sudo snap install hugo

Windows

choco install hugo-extended

上面的下载方式是官方推荐的，笔者的主要工作环境是Windows，但并不采用上述的下载方式，因为choco是一个包管理器，本身也需要下载（笔者不喜欢因为一个功能而去下载另一个功能，导致整个环境特别臃肿），可以采用以下方法去下载：

到Hugo的GitHub仓库中，找到Tags

选择最新的版本（本文创作时最新版本是v0.138.0）

一直往下滑，可以看到一堆Assets资源，找到Windows，且带有extended版本的，本文是根据Hugo框架下的stack主题来构建的，如果你查看过stack的官方文档，可以发现，其中也强调了是以哦那个extended（拓展）版本，才能完成该主题的全部功能搭建。
下载完成后，你会得到一个Hugo静态网站生成器的exe执行文件，该执行文件可以帮助你生成一个静态网站的全部内容。此步骤可做可不做：将hugo所在的目录放在系统环境变量path中。笔者是做了这一步的，这一步的作用是，无论你在那个目录下，都能使用hugo命令。如不添加，则当你生成了一个静态网站资源，你需要将hugo.exe文件拖入静态网站资源的目录下，以便你日后在在目录内调用hugo命令。

在控制台（如果没有添加环境变量，则需要在有hugo.exe的目录下执行）使用hugo version命令测试hugo是否安装成功，如果安装成功，则输出如下

1
2
3
4


D:\HugoBlog\dev>hugo version
hugo v0.136.5-46cccb021bc6425455f4eec093f5cc4a32f1d12c+extended windows/amd64 BuildDate=2024-10-24T12:26:27Z VendorInfo=gohugoio

D:\HugoBlog\dev>

创建新的站点

在cmd中（如果没有配置全局路径，在hugo.exe目录下使用该命令）使用命令

1

hugo new site yoursitename #yoursitename 是你的站点文件夹名称， 可以使用dev或自己起个名字

上面截图显示了创建新的站点成功，并且会给你一些提示，按照提示走就可以花很少的时间搭建出一个静态网站

Hugo会在这个D:\HugoBlog目录下自动新建一个名为AHugoBlogSite的目录，如下图所示：

进入AHugoBlogSite目录

1

cd AHugoBlogSite

挑选主题

Hugo下载好后，就可以开始挑选自己喜欢的主题，可以在Hugo官网下挑选（Complete List | Hugo Themes），每个主题都可以点进去查看详细信息与下载地址，笔者这里使用了stack主题，特别适合用于搭建个人博客网站。可以通过Hugo Themes中选中stack主题，进去Download，也可以在GitHub上直接搜索CaiJimmy/hugo-theme-stack: Card-style Hugo theme designed for bloggers，仿照上面下载hugo的方法找到对应位置下载源码（source code）压缩包即可。

如果有兴趣为该主题添砖加瓦的同学，也可以给这个主题作者提交Issues！

Stack

解压主题

将stack主题的源码解压到AHugoBlogSite\themes目录下（接下来为了方便，AHugoBlogSite统称为站点目录）。

将解压的目录名称中的版本号删除，改成像我一样hugo-theme-stack

值得注意的是，如果你想换其它主题，或者你一开始便不打算下载stack主题，操作也是一样的，同样将版本号删除，并将yaml配置文件中的主题改成对应的主题目录名称即可（后面会提及）

从主题文件中复制两个重要文件

在解压的目录（hugo-theme-stack）下，有一个样例目录名为：exampleSite，里面有两个非常重要的东西，一个是content目录，一个是hugo.yaml配置文件，将这两个文件复制出来

放到站点目录下

将原本的默认配置文件hugo.toml删除，用我们复制过来的hugo.yaml做配置文件

注意：在content\post\目录下，有一个rich-content的目录==删掉==，post目录下存放的就是你的博客内容，这个rich-content博客中做了一些引用Youtube的样例操作，可能会导致你运行失败，这些国外网站可能会导致你访问超时

修改配置

打开刚才复制过来的hugo.yaml

更换主题

可以看到，这里主题选择的是hugo-theme-stack，如果你想更换其它的主题，只需下载其它主题的源码到themes\目录下，并将配置文件中的主题换掉即可

以下笔者就不截图了，以代码段形式展现笔者修改了的部分:

笔者将url的重定向到自己的GitHub仓库，下一篇讲部署到GitHub上时会提及

1

baseurl: https://Lyrical-wander.github.io

修改了著作权，当然，这个著作权是指本博客的著作权，而非hugo也非该主题

1

copyright: Lyrical Wander

将默认语言修改为中文

1

DefaultContentLanguage: zh-cn

修改以下配置，据说可以更精确的计算读文章的时长

1

hasCJKLanguage: true

这里修改的是博客左上方的标题，有中英两个版本，但笔者的博客全是中文博客，还没有做国际化的打算

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


languages:
 en:
 languageName: English
 title: LyricalWander's Blog
 weight: 1
 params:
 sidebar:
 subtitle: We have a long life,but just own death and love
 zh-cn:
 languageName: 中文
 title: 苏三有春的博客
 weight: 2
 params:
 sidebar:
 subtitle: 人生茫茫，唯死亡与爱而已

这个参数是指一页展示多少篇文章

1
2


pagination:
 pagerSize: 5

你可以在static目录下存放你博客的图标，将名称改为favicon.ico

1
2


 favicon: /favicon.ico 
 # e.g.: favicon placed in `static/favicon.ico` of your site folder, then set this field to `/favicon.ico` (`/` is necessary)

以下参数是修改你的头像以及添加emoji（头像右下角的表情），首先将图片名称改为avatar.png，并添加到assets\img\目录下，如果没有img目录可自行创建，然后将参数修改：

1
2
3
4
5
6
7


 sidebar:
 emoji: 🧐 
 subtitle: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 avatar:
 enabled: true
 local: true
 src: img/avatar.png

修改下面的参数，可以添加或修改头像下面的快捷链接小图标，笔者增加了链接进入笔者B站主页和进入笔者CSDN主页的快捷链接，图标以SVG格式存放在assets\icons\目录下，值得注意的是，下面参数icon是图标的文件名去掉.svg，比如brand-bilibili.svg去掉.svg，如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


 social:
 - identifier: github
 name: GitHub
 url: https://github.com/Lyrical-wander
 params:
 icon: brand-github

 - identifier: bilibili
 name: Bilibili
 url: https://space.bilibili.com/28788259
 params:
 icon: brand-bilibili

 - identifier: csdn
 name: CSDN
 url: https://blog.csdn.net/whale_cat
 params:
 icon: brand-coinbase

现在我们创建我们的博客看看

命令：

1

hugo server -D

注意：

必须是在站点目录下使用该命令。（上面我们通过cd AHugoBlogSite进入了目录）

必须是D而不是d

运行命令后会出现以下信息

可以看见，通过访问http://localhost:1313即可访问博客

开始编写文章

文章目录结构

首先看一下文章目录结构，文章都保存在content目录下：

看看对应的网站结构：

其实无论是page，categories，post，都可以看作一个一级目录，然后每一篇文章，每一个分类，亦或者每一个侧边栏的选项，都是二级目录，二级目录下才是真正的内容，比如，在categories目录下：

有这么四个二级目录，分别代表了四个我已经创建并附带说明的分类

值得注意的是，你看我的博客分类有许多，比如网络爬虫，操作系统等，都没有在categories目录下创建，但在分类中依然存在，这是因为，我将某篇文章归类为网络爬虫，但是还没有创建这个分类，因此Hugo自动地帮我创建一个默认分类，把带有网络爬虫的文章收录在一起，但是这分类没有初始图片，没有说明，如下图所示：

这个分类中没有默认图片，也没有简介，技术杂谈这个分类就有，如下图所示

如何写博文

我写博文采用的是markdown格式，这个格式我非常熟悉，写起来也特别舒服，使用Typora工具，写markdown手感特别好。

makrdown格式没什么好说的，学起来也很快，在写博文的时候需要注意的是开头携带的信息，如下图所示：

这是文章开头的内容，上面我打开了typora的源码模式。如果是普通的编写模式，则是下面这个样子的：

可以看到，Typore自动的把---这个识别成分割线，把源码中用---包起来的内容用分割线与下面内容隔开。

在这里面，你需要注意的是：

title：文章标题

description：副标题，简介

date：编写日期

image：文章最上方的图片

categories：分类

tags：标签

分类和标签的内容可以是中文，可以多个，但需要采用[“xx”,“xx”]的格式

:后需要加一个空格，再输入内容

后面的就按照正常markdown创作即可

值得注意的是：

博文采用markdown格式，命名规则为：index.语言.md，这里因为我的默认语言是中文，就不用携带语言，即：‘zh-cn’，因此只需要命名为index.md即可。

总结

至此，你已经搭建了你的个人博客，并且可以开始写文章啦，更多关于stack主题的美化或修改可以看stack文档Stack | Card-style Hugo theme designed for bloggers

同时，下面一篇文章会介绍如何将博客部署到GitHub上，可以通过GitHub的pages功能，创建一个可以在公网访问的博客网站，很感谢你读到这里，祝你变得更强！

Blog on 苏三有春的博客

Hugo 博客维护踩坑记：主题迁移、暗色模式与 SCSS 优先级

为什么要用 Git Submodule

Git Submodule 是什么

Submodule 的实际优势

背景

第一步：把嵌入的主题改成 submodule + fork

坑一：submodule 指向的是 fork 的 v4.x，和博客用的 v3.9.x 不兼容

坑二：Hugo v0.152.2 废弃 API，直接编译失败

坑三：assets/scss/custom.scss 暗色模式覆盖不生效（重点）

坑四：部署日志显示成功，但 .github.io 仓库没更新

总结：Hugo 主题定制的优先级规则

附：本次改动总览

基于Hugo构建一个属于自己的博客（二）

前言

创建仓库

修改配置

上传代码

启用pages功能

小结

自动化部署

创建仓库

修改代码

创建.gitignore文件

生成token并创建yaml配置文件

上传代码

基于Hugo构建一个属于自己的博客（一）

前言

Hugo

Hugo下载

创建新的站点

挑选主题

Stack

解压主题

从主题文件中复制两个重要文件

放到站点目录下

修改配置

更换主题

开始编写文章

文章目录结构

如何写博文

总结

坑三：`assets/scss/custom.scss` 暗色模式覆盖不生效（重点）

坑四：部署日志显示成功，但 `.github.io` 仓库没更新