博客搭建 on 寻 Mi 处

Stack 主题用了半年，这些地方我都改过

Fri, 25 Jul 2025 11:35:00 +0800

Stack 这个主题，默认配置出来的样子已经挺好了。我用它就是因为开箱即用，不用折腾。

但用久了总会想改点东西。有些是审美上的，有些是功能上的，有些纯粹是强迫症。

改的时候我一直坚持一个原则，能不碰主题源码就不碰。因为主题是 submodule，你一改，下次更新就冲突。

所以下面的改动，全部通过 Hugo 的覆盖机制实现。要么是配置，要么是在 layouts 下面放同名的文件。

先搞清楚覆盖是怎么工作的

Hugo 查找模板的顺序是，项目根目录的 layouts 优先，然后是主题的 layouts。

所以你想改主题里的 layouts/partials/footer.html，不需要去 themes/hugo-theme-stack/layouts/partials/ 改，只需要在项目的 layouts/partials/ 下放一个同名文件，Hugo 会自动用你的。

这个机制叫 template lookup order，官方文档里有完整的顺序表。

配置也一样。主题的 exampleSite/config/_default/ 是默认值，你在自己的 config/_default/ 里写同名文件，就是覆盖。

首页的副标题

Stack 的首页左侧有个大标题和一段描述，来自 config/_default/params.toml：

[sidebar]
    emoji = "���"
    subtitle = "记录一些折腾的过程"
    avatar = "img/avatar.png"

emoji 会显示在标题旁边。subtitle 是标题下面那行小字。

avatar 的路径是相对于 assets 目录的。所以你要把头像放在 assets/img/avatar.png，不是 static。

这一点容易搞混。Stack 用的是 Hugo Pipes 处理图片，assets 下的东西才能被处理。

社交图标

[[params.social]]
    name = "github"
    icon = "brand-github"
    weight = 10
    url = "https://github.com/yourname"

[[params.social]]
    name = "rss"
    icon = "rss"
    weight = 20
    url = "/index.xml"

icon 用的是 Tabler Icons 的名字。完整列表在 tabler-icons.io 上，找的时候去掉前面的 brand- 或者 outline- 前缀看。

weight 决定顺序，小的在前。

侧边栏的菜单

[[menu.main]]
    identifier = "home"
    name = "首页"
    url = "/"
    weight = 10

[[menu.main]]
    identifier = "archives"
    name = "归档"
    url = "/archives/"
    weight = 20

[[menu.main]]
    identifier = "search"
    name = "搜索"
    url = "/search/"
    weight = 30

注意 url 结尾的斜杠。Hugo 的 baseURL 带斜杠，页面 URL 也带，不加斜杠会导致相对路径解析出错。

归档页和搜索页需要在 content/page/ 下面建对应的目录，不然点了 404。

代码块的样式

Stack 的代码高亮用的是 Chroma。默认的配色是 monokai，我觉得在亮色背景下太刺眼。

改成 github：

[markup.highlight]
    noClasses = false
    codeFences = true
    guessSyntax = false
    lineNos = false
    lineNumbersInTable = false
    tabWidth = 4
    style = "github"

noClasses = false 这个设置很关键。它让 Chroma 输出 class 而不是内联样式，这样你才能用自己的 css 覆盖配色。

guessSyntax = false 是我改的。默认是 true，它会猜代码块的语言，猜错了反而难看。显式写语言更可靠。

暗色模式下的配色，Stack 有单独的处理。在 assets/scss/custom.scss 里：

[data-scheme="dark"] {
  .highlight {
    .chroma {
      background-color: #1e1e1e;
    }
  }
}

代码复制按钮

Stack 本身没带这个功能，但实现起来不难。

先加一个 partial，layouts/partials/article/components/copy-button.html：

<button class="copy-code-button" aria-label="复制代码">
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
    <rect x="9" y="9" width="13" height="13" rx="2"></rect>
    <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
  </svg>
</button>

然后在 assets/js/custom.js 里加事件：

document.querySelectorAll('pre > code').forEach((codeBlock) => {
  const button = document.createElement('button');
  button.className = 'copy-code-button';
  button.textContent = '复制';
  button.addEventListener('click', async () => {
    await navigator.clipboard.writeText(codeBlock.innerText);
    button.textContent = '已复制';
    setTimeout(() => { button.textContent = '复制'; }, 1500);
  });
  codeBlock.parentElement.style.position = 'relative';
  codeBlock.parentElement.appendChild(button);
});

navigator.clipboard 需要 https，http 下是 undefined。本地开发用 localhost 是可以的，因为浏览器把 localhost 当安全上下文。

Stack 会自动加载 assets/js/custom.js，不用额外配置。这个约定挺方便的。

目录的样式

Stack 的 TOC 在文章右侧，宽屏下才显示。我改了一下它的位置和宽度。

在 assets/scss/custom.scss 里：

@media (min-width: 1280px) {
  .article-toc {
    position: sticky;
    top: 2rem;
    max-height: calc(100vh - 4rem);
    overflow-y: auto;
  }
}

position: sticky 让目录在滚动的时候跟着走，但滚到底部就停住。这个体验比固定定位好，不会挡住页脚。

页脚的备案号

国内的站需要放备案号，链接到工信部的网站。

layouts/partials/footer/footer.html：

<footer class="footer">
    <div class="container">
        <div class="footer-content">
            {{- with .Site.Params.footer.since }}
            <span>&copy; {{ . }} - {{ now.Year }}</span>
            {{- end }}
            <span>{{ .Site.Params.footer.copyright }}</span>
            <a href="https://beian.miit.gov.cn/" target="_blank" rel="noopener">
                京ICP备xxxxxxxx号
            </a>
        </div>
    </div>
</footer>

rel="noopener" 一定要加。外链带 target="_blank" 而不加 noopener，被链接的页面可以通过 window.opener 操作你的页面，这是个经典的安全问题。

文章卡片的摘要长度

Stack 默认取文章的前若干字符做摘要。这个长度可以在 front matter 里用 description 控制，也可以在配置里全局设：

1
2

[params.article]
    summary = "auto"

auto 是自动截取。如果你想让每篇文章用自己的 description，设成 "description"。

我觉得用 description 更好，因为自动截取经常截在奇怪的地方，句子断在半截。

暗色模式的默认值

Stack 默认跟随系统。但我想让它默认是暗色。

assets/js/custom.js：

document.addEventListener('DOMContentLoaded', () => {
  const saved = localStorage.getItem('prefers-color-scheme');
  if (!saved) {
    document.documentElement.dataset.scheme = 'dark';
    localStorage.setItem('prefers-color-scheme', 'dark');
  }
});

Stack 自己用 localStorage 存用户的选择，键名是 prefers-color-scheme。我们先检查有没有存过，没存过就设成 dark。

这个改动要小心，因为它会在页面渲染之后才执行，可能有一瞬间的闪烁。要彻底解决得在 <head> 里内联一段脚本，但那就要改 head.html 了。

归档页的分组

Stack 的归档页默认按年份分组，这个我觉得挺好的，没改。

但我加了一个显示每年文章数的功能。

layouts/partials/page/archive.html 里，找到渲染年份的地方，改成：

<h2 class="archive-year">
  {{ .Key }}
  <span class="archive-count">{{ len .Pages }}</span>
</h2>

.Pages 是 Hugo 的分组对象里的字段，包含这一组的所有页面。len 拿到数量。

搜索

Stack 内置了搜索，用的是 fuse.js 加一个生成的 index.json。

需要在配置里开：

1
2
3

[params]
    [params.search]
        enable = true

然后建一个 content/page/search/index.md，front matter 里写：

---
title: "搜索"
layout: "search"
---

layout: search 会让 Hugo 用主题里的搜索模板。

搜索的索引文件在 public/index.json，Hugo 构建的时候自动生成。如果搜索没结果，先看看这个文件在不在。

一个我踩过的坑

改完 custom.scss 之后，样式没生效。

原因是 Hugo 的 resources 缓存。它会把编译过的 scss 存在 resources/_gen/ 下面，改了源文件但缓存没失效的时候，用的还是旧的。

解决办法：

`1`	`hugo --gc`

或者手动删掉 resources/_gen/。我后来在部署脚本里固定加了 --gc，就没再遇到。

主题更新的处理

因为所有改动都在项目目录里，更新主题不会冲突。

`1`	`git submodule update --remote themes/hugo-theme-stack`

跑完之后看一眼有没有报错，然后本地 hugo server 确认样式没坏。

有一次更新之后，侧边栏的布局变了，因为主题改了一个 class 名。我的 custom.scss 里覆盖的规则就失效了。这种情况只能看一眼 release notes，手动改。

现在

改了这么多，主题的骨架还是原样，只是细节上更合我的习惯。

我一直觉得，主题定制最好的状态是，别人看不出你用了什么主题，但你自己用着舒服。

过度定制的反面教材我也见过，有人把主题改得面目全非，结果每次更新都要花一天合并冲突。那还不如自己从头写一个。

我的建议是，先列出来你真正需要的改动，通常不超过十条。剩下那些"看起来可以更好"的，忍住。

把 Hugo 博客的加载速度从三秒压到八百毫秒

Sun, 29 Dec 2024 20:18:00 +0800

博客搭起来之后，我有一阵子特别在意 Lighthouse 那个分数。

第一次跑的时候，移动端性能 41 分，红色的。首屏内容绘制三点二秒，最大内容绘制四点一秒。这个成绩放在 2024 年，属实难看。

花了一个周末逐项处理，现在稳定在 96 分左右，首屏八百毫秒。这篇记录一下具体做了什么，哪些有用，哪些是白费劲。

先搞清楚慢在哪

别一上来就乱改。先跑一遍 Lighthouse，看它给的诊断项。

打开 Chrome 开发者工具，Lighthouse 标签页，选 Mobile，跑一次。跑完会给你一堆建议，按影响大小排序。

我那次排在最前面的是三件事。图片没有指定尺寸导致布局偏移，字体加载阻塞渲染，还有一个第三方脚本。

改之前先记一下基线，不然改完不知道有没有变好。

图片是最大的问题

我博客的文章配图是直接从手机相册里拖出来的，一张四兆。首页卡片显示的是缩略图，但它加载的其实是原图，浏览器自己缩。

这就很浪费。一个用户打开首页，要下十几兆的图片，手机上还容易因为内存不足崩掉。

Hugo 内置了图片处理，用 Page Bundle 就能直接调：

1
2
3

{{ $img := .Resources.Get "cover.jpg" }}
{{ $small := $img.Resize "800x webp q80" }}
<img src="{{ $small.RelPermalink }}" width="{{ $small.Width }}" height="{{ $small.Height }}" alt="封面">

Resize "800x webp q80" 的意思是，宽度缩到 800，保持比例，转成 webp 格式，质量 80。webp 比 jpg 小百分之三十左右，肉眼几乎看不出区别。

如果要响应式，用 srcset：

{{ $img := .Resources.Get "cover.jpg" }}
{{ $s := $img.Resize "480x webp" }}
{{ $m := $img.Resize "800x webp" }}
{{ $l := $img.Resize "1200x webp" }}
<img
  src="{{ $m.RelPermalink }}"
  srcset="{{ $s.RelPermalink }} 480w, {{ $m.RelPermalink }} 800w, {{ $l.RelPermalink }} 1200w"
  sizes="(max-width: 600px) 480px, (max-width: 900px) 800px, 1200px"
  width="{{ $m.Width }}" height="{{ $m.Height }}"
  loading="lazy" alt="封面">

width 和 height 一定要写。这是 Lighthouse 那个"图片元素没有明确的宽度和高度"的根源。有了这两个属性，浏览器在图片加载之前就能预留出空间，不会发生布局偏移。CLS 这个指标直接从 0.24 降到 0.01。

loading="lazy" 让首屏之外的图片延迟加载。但首屏的图片不要加，加了反而会拖慢 LCP。

字体

Stack 主题默认用的是系统字体栈，本来不该有这个问题。但我自己加了个思源黑体，从 Google Fonts 拉的。

问题在于，Google Fonts 的那个 css 是渲染阻塞的。浏览器必须等它下载完，才能决定用什么字体显示文字。国内访问 Google 的域名还经常超时，一等就是好几秒。

解决办法是把字体下到本地，自己托管：

1
2

mkdir -p static/fonts
wget -O static/fonts/NotoSansSC-Regular.woff2 "https://..."

然后在 css 里：

@font-face {
  font-family: 'Noto Sans SC';
  src: url('/fonts/NotoSansSC-Regular.woff2') format('woff2');
  font-display: swap;
  unicode-range: U+4E00-9FFF;
}

font-display: swap 是关键。它让浏览器先用后备字体显示文字，等自定义字体下载完了再替换。用户不会看到一片空白。

中文字体文件很大，完整的思源黑体有十几兆。所以我又做了一步，用 fonttools 做子集化，只保留常用的三千多个字：

1
2

pip install fonttools brotli
pyftsubset NotoSansSC-Regular.otf --text-file=common.txt --flavor=woff2 --output-file=NotoSansSC-subset.woff2

这样能从十几兆压到六百多 KB。

不过说实话，后来我干脆把自定义字体删了，直接用系统字体栈：

`1`	`font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", sans-serif;`

效果上没什么差别，还省了六百 KB 的下载。这是我折腾一圈之后最实际的一个决定。

渲染阻塞的 css 和 js

Hugo 生成的 css 是通过 resources.Get 和 minify 处理的，Stack 主题已经做得不错了。

但我检查的时候发现，有个 custom.css 是同步加载的，它在 <head> 里，会阻塞渲染。

如果这个 css 不大，可以直接内联：

1
2

{{ $css := resources.Get "css/custom.css" | minify }}
<style>{{ $css.Content | safeCSS }}</style>

内联的好处是省掉一次请求。坏处是不能缓存，每次都要跟着 html 一起下载。所以只适合小文件，几百字节以内。

大一点的用 preload：

1
2

<link rel="preload" href="/css/custom.css" as="style">
<link rel="stylesheet" href="/css/custom.css" media="print" onload="this.media='all'">

这个写法有点绕，原理是先以 media="print" 加载，这样浏览器不会把它当渲染阻塞资源，加载完了再通过 onload 把 media 改成 all。

js 那边，我给所有非关键的脚本都加了 defer：

`1`	`<script src="/js/main.js" defer></script>`

defer 表示下载不阻塞解析，等 html 解析完了再按顺序执行。比 async 更可控，因为 async 的执行顺序不确定。

去掉那个第三方脚本

我在侧边栏加了个访问量统计，用的是某个第三方服务的小挂件。它加载的时候会额外拉三个资源，其中一个还卡了两秒。

看了下它的实现，就是一个 img 加一段脚本。我把它删了，换成了自己写的，用 Cloudflare 的 Workers 记录访问，前端只请求一个自己域名下的接口。

从三个跨域请求变成一个同域请求，这一项就省了将近一秒。

这个教训是，第三方的挂件比自己写的贵得多。你控制不了它的性能，也控制不了它什么时候挂。

缓存策略

静态博客的缓存可以设得很激进。我在 nginx 里给静态资源设了一年：

location ~* \.(css|js|woff2|jpg|jpeg|png|webp|svg)$ {
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable";
}

前提是文件名带指纹。Hugo 的 resources 管道默认会给处理过的资源加 hash，比如 custom.a1b2c3d4.css，改内容就改名字，所以缓存一年也不会出问题。

html 不能这么设，我给了十分钟，加上 must-revalidate。

结构化数据

SEO 这块，除了 title 和 description，最重要的是给搜索引擎结构化数据。

Stack 主题自带了一部分，但不够全。我加了一段 JSON-LD，放在 layouts/partials/head.html 的扩展位置：

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": {{ .Title }},
  "datePublished": {{ .Date.Format "2006-01-02T15:04:05Z07:00" }},
  "dateModified": {{ .Lastmod.Format "2006-01-02T15:04:05Z07:00" }},
  "author": {"@type": "Person", "name": "{{ .Site.Params.author }}"},
  "mainEntityOfPage": {"@type": "WebPage", "@id": {{ .Permalink }}}
}
</script>

这个能让搜索结果里显示作者、日期这些信息，点击率会高一些。

sitemap 和 robots

Hugo 默认会生成 sitemap.xml，不用管。

robots.txt 我用的是模板：

User-agent: *
Allow: /
Disallow: /page/

Sitemap: {{ .Site.BaseURL }}sitemap.xml

Disallow: /page/ 是分页页，这些页面内容重复，让爬虫抓了没意义，还分散权重。

收录的情况

提交了 sitemap 之后，我在 Google Search Console 里看，首页三天收录，文章页大概一周。

百度的收录慢很多，而且它对这个域名的抓取频率很低。我后来在百度站长平台手动提交了几次，情况好了一点，但依然不如 Google。

这个我没太纠结。写博客主要是给自己留个记录，有人搜到是意外收获。

那些没用的事

有几个优化我试过但放弃了。

一个是 preconnect 到各种第三方域名。我加了之后 Lighthouse 分数反而掉了两分，因为每个 preconnect 本身也要开销，域名一多就得不偿失。

一个是把 css 全内联。文件一大，html 体积涨到两百多 KB，首字节时间反而变长。现在只内联关键的那部分。

还有一个是 Service Worker 做离线缓存。技术上是能跑，但博客更新频率低，用户很少重复访问同一篇，收益不明显，还容易因为缓存版本没更新导致看到旧内容。

现在的成绩

移动端 96 分，桌面端 99。首屏八百毫秒左右，LCP 一点二秒。

这个分数在个人博客里算不错的，但我越来越觉得分数本身没那么重要。真正有用的是那几个具体的改动，图片压缩、字体本地化、去掉第三方脚本。这三件事做完，体验上的提升是能感觉到的，分数只是顺带的结果。

如果你的博客也慢，我建议先看图片。十有八九，问题就在那儿。

折腾了三种博客程序之后，我最后还是回到了 Hugo

Tue, 12 Nov 2024 16:06:00 +0800

我的博客换过三次。

最早是 WordPress，插件装了一堆，功能确实全，但每次后台点一下都要等两三秒。那台 1 核 1G 的 VPS 跑 PHP 加 MySQL，内存常年飘在 90% 以上，隔三差五就被 OOM killer 干掉一次。

后来换 Hexo。静态生成，快是快，但 node_modules 那个目录，每次重装都像是在抽奖。有一次 npm install 装了两百多个包，其中一个包依赖的包又依赖别的包，最后卡在一个早就没人维护的模块上，编译失败。

再后来听人提 Hugo。我一开始觉得它就是个静态生成器，和 Hexo 差不多，没什么非换不可的理由。直到我看见有人用它构建几千篇文章只要几秒钟。

现在这个站跑在 Hugo 上，用了快一年，中间没有一次因为构建本身出问题。

装

Windows 上最省事的是用 scoop：

`1`	`scoop install hugo-extended`

一定要装 extended 版本。普通版本不支持 SCSS 和 Sass，而 Stack 主题的样式是用 SCSS 写的，装错版本会构建失败，报错信息还特别含糊。

Linux 上直接下二进制：

1
2
3

wget https://github.com/gohugoio/hugo/releases/latest/download/hugo_extended_linux-amd64.tar.gz
tar -xzf hugo_extended_linux-amd64.tar.gz
sudo mv hugo /usr/local/bin/

装完验证：

`1`	`hugo version`

输出里带 extended 字样就对了。

建站

1
2

hugo new site blog
cd blog

生成的目录结构是这样：

blog/
├── archetypes
├── assets
├── content
├── data
├── i18n
├── layouts
├── static
├── themes
└── hugo.toml

content 是文章，static 是原样拷贝的文件，themes 是主题。assets 这个目录值得说一下，放进去的东西会经过 Hugo 的管道处理，比如 SCSS 编译、图片压缩、JS 打包。

选主题

我试过好几个，最后停在 Stack 上。

它的视觉风格比较克制，左侧固定侧边栏，文章列表卡片式，暗色模式做得挺舒服。功能上该有的都有，标签、分类、归档、搜索、代码高亮、目录，不用自己补。

装主题有两种方式，submodule 和直接下载。submodule 干净一些：

1
2

git init
git submodule add https://github.com/CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

用 submodule 之后，更新主题就是 git submodule update --remote，不会污染自己的仓库。

配置

hugo.toml 里最基本的东西：

baseURL = "https://blog.mibase.top/"
languageCode = "zh-cn"
title = "明月小站"
theme = "hugo-theme-stack"

[pagination]
  pagerSize = 10

[permalinks]
  posts = "/p/:slug/"

[markup]
  [markup.highlight]
    noClasses = false
    codeFences = true
    lineNos = false

[permalinks] 那段决定了文章的 URL 结构。我设成 /p/:slug/，是因为之前见过别人的站用日期做路径，文章一多，URL 长得没法记。用 slug 更短，也更容易分享。

注意 Hugo 从 0.128 开始把 paginate 改成了 pagination.pagerSize。老教程里写的 paginate = 10 现在会报警告。

Stack 主题还需要一份自己的配置，放在 config/_default/ 下面。主题仓库里的 exampleSite 目录有一份完整的示例，复制过来改最省事。

`1`	`cp -r themes/hugo-theme-stack/exampleSite/config/_default/* config/_default/`

然后改 config/_default/hugo.toml 里的 baseURL、title，改 params.toml 里的头像、社交链接、侧边栏设置。

写下第一篇

`1`	`hugo new content posts/hello-world/index.md`

注意这里写的是 posts/hello-world/index.md，不是 posts/hello-world.md。

这是 Hugo 的 Page Bundle 机制。用目录加 index.md 的形式，可以把图片和文章放在一起，引用的时候直接写相对路径：

`1`	`![截图](screenshot.png)`

不用管最终部署到哪个路径，Hugo 会自己处理。这个设计比把图片全塞进 static 里要好，因为文章和它的资源绑在一起，删文章的时候资源也跟着删，不会留下垃圾。

生成的 front matter 长这样：

---
title: "Hello World"
date: 2024-11-12T16:06:00+08:00
draft: true
---

draft: true 表示草稿，本地 hugo server 能看到，但构建的时候会被排除。写完改成 false 才会发布。

这个机制挺有用的。有时候写一半的东西不想让人看到，就留着 true，等写完再改。

本地预览

`1`	`hugo server -D`

-D 是显示草稿。默认只监听 localhost:1313，如果要让局域网里的手机也能看：

`1`	`hugo server -D --bind 0.0.0.0 --baseURL http://192.168.1.10:1313`

--baseURL 这个参数不加的话，手机打开页面样式是乱的，因为 css 的路径还指向 localhost。

Hugo 的 server 有热重载，改文章、改模板都会立刻刷新浏览器。改配置文件有时候需要重启，因为它不监听配置文件的变化。

构建

`1`	`hugo --minify --gc`

产物在 public 目录。

--minify 会压缩 html、css、js 和 json，一般能小 20% 左右。--gc 清理掉不再被引用的缓存文件，防止 resources 目录无限膨胀。

有个参数我一开始不知道，--printPathWarnings，它会告诉你哪些页面有重复路径。文章多了之后很有用，能提前发现 slug 冲突。

部署

我把 public 目录通过 git 钩子同步到服务器，那套流程写在另一篇里了。简单说就是本地 push，服务器上的钩子执行 hugo 构建，nginx 指向产物目录。

这个方案的好处是不需要额外的 CI 服务，坏处是构建在服务器上跑，服务器得装 Hugo。我服务器上装的是 extended 版本，和本地保持一致。

目录约定

用了一段时间，我把目录固定成了这样：

content/
├── page/
│   ├── about/index.md
│   └── links/index.md
└── posts/
    ├── hello-world/index.md
    └── another-post/index.md

posts 下面全是文章，一篇一个目录。page 下面放独立页面，比如关于、友链。Stack 主题默认就是这么分的。

分类和标签不用建目录，写在 front matter 里就行，Hugo 会自动生成列表页。

一个容易踩的坑

Hugo 的 date 字段如果没有时区，会按 UTC 解释。

我第一篇文章写的是 date: 2024-11-12 16:06:00，构建出来发现时间比实际早了八小时。后来改成带时区的格式 2024-11-12T16:06:00+08:00 才对。

这个在本地看不出来，因为 hugo server 用的是本地时区。部署到服务器上，服务器是 UTC，就露馅了。

现在回头看

三次换博客程序，每次的动机都不一样。

WordPress 是图省事，Hexo 是图轻快，Hugo 是图稳定。

现在这套东西，构建三秒，部署十秒，改一行配置立刻能看到效果。中间没有数据库，没有后台，没有需要重启的服务。它就是一堆文件。

这种简单带来的安心感，是前面两个方案没给过我的。

一些我后来才明白的细节

hugo.toml 里的 baseURL 结尾一定要带斜杠。写成 https://blog.mibase.top 而不是 https://blog.mibase.top/，生成的 rss 和 sitemap 里的链接会缺一个斜杠，有些抓取工具会因此报错。

content 目录下以 _index.md 开头的文件是列表页，不是文章。posts/_index.md 定义了文章列表页的标题和排序方式。如果你不小心把文章命名成 _index.md，它不会出现在文章列表里，反而会变成那个目录的列表页。

草稿的 draft: true 只影响构建，不影响 hugo server。只要加了 -D，草稿一样能看到。有时候我写完忘了改，本地看着好好的，部署上去发现没有这篇，才想起来。

resources/_gen 这个目录是 Hugo 的缓存，可以删，删了会重新生成。但它不要提交到 git 里，会污染 diff。.gitignore 里加上这一行：

1
2

resources/_gen/
public/

public 也不该提交。它是构建产物，每次部署都会重新生成，提交进去只会让仓库变大。

如果重新来一次

我会在第一天就把这些东西配好，而不是用了半年才补。

hugo.toml 里的 enableRobotsTXT，加上之后会自动生成 robots.txt。

[markup.goldmark.renderer] 里的 unsafe = true，加上之后才能在文章里直接写 html。默认是关闭的，是为了安全，但自己的博客自己写内容，没什么风险。

[outputs] 里给首页加上 JSON，这样才有搜索用的 index.json。Stack 的搜索依赖这个。

这些都是一次性的配置，配好之后就不用管了。但不知道的时候，会卡很久。