主题是 Hugo-theme-next，有一些修改。虽然支持夜间模式，但是不太会调色，有一些自定义的样式在夜间模式下效果不好。所有颜色都是保证在日间模式下易读而选择的，如果夜间模式难以阅读可以切换回来。因为动画速率太慢，调快也觉得晃眼，就关掉了。

• 2025.10.3 验证需要用 Release v0.143.1 · gohugoio/hugo 来渲染。已验证到 v0.146.x 开始不可用，v150.0 可用。参考 New template system in Hugo v0.146.0 。
• 2025.10.4 通过将一些模板中的 partials/ 前缀去除，兼容 v0.146.x，但是 achives/ 无法显示列表了。魔改了旧主题还没适配，目前暂时使用 hugo v0.143.1，不做调整。

✨ 一些改动

1. 改变了左侧 TOC 的行距，使得多行标题能够更容易被区分开。
2. 增加了 GitHub 风格警告支持。以前使用脚本支持，现在使用钩子重写。
3. 为 Compiler Explorer 链接启用代码预览，把鼠标悬停在链接上就能看到代码文本。
4. Markdown 相对路径链接（其他文章或图片）。以前使用 404.html 支持，现在使用钩子重写。新增 Obsidian 风格的 [| width] 宽度标记支持。
5. 按照顶级元素数量来摘取文章在首页的总结。

💥 Hugo 写作的坑

YAML Front Matter 的类别要使用 categories 而不是 category，而且类型一定要是字符串的列表，而不是单个字符串（不然有些 html 模板不能正确处理）。

文本高亮（==文本== 渲染成 <mark>文本</mark>）

这是 2024 年 5 月更新的功能，升级 Hugo-extended 到 0.126.0 以上的版本并修改配置即可。

markup:
  goldmark:
    extensions:
      # https://github.com/goHugoio/Hugo/commit/ca9a77ef92eb0cb7bb5193e4e3afa4abb26d577c
      extras:
        insert:
          enable: false
        mark:
          enable: true
        subscript:
          enable: false
        superscript:
          enable: false

GitHub 样式的警告窗口

样式是参考 markdown-it-github-alerts 糊的。然后添加 DOMContentLoaded 监听，查找符合要求的 <blockquote> 元素并替换。

Emoji 表情

使用过 Hugo-mod-twemoji 的网站构建时替换表情为资源图片的方案，但是构建速度显著变慢且没有正常替换。

Twemoji 的 twemoji.parse(document.body); 替换文本也使用过，需要给表情图片加上 display: inline-flex 的显示方式保证不换行，但是每次加载新页面的表情时总有 500ms 以上的延迟，因为浏览器没有办法对表情图片资源做出预测，只能看到资源被需要才去请求。

现在是直接使用了 twemoji 字体，除了第一次需要下载字体文件之外，新页面的表情都是没有重新下载的过程的。为了解决 Noto Sans SC 字体覆盖 emoji 内容、还有 Twemoji 字体无法显示部分拉丁字符的问题，字体的使用顺序为 Noto Sans > Twemoji > Noto Sans SC，尽管 Noto Sans SC 应该是 Noto Sans 的超集。其他字体也得根据情况调整，这算是直接使用字体而不是图片替换的一个缺点。我现在是参考 https://leader.js.cool/basic/knowledge/fonts/ 使用系统自带的字体。

代码块

用的是 Hugo-theme-next 支持的 solarized-dark。这个高亮风格在夜晚、日间主题下显示的效果都比较好，只需要微调一下主体字的颜色。

当代码块过宽而不得不被折叠时，右上角的粘贴标志本应该保持不变，但我使用的 v4.5.3 右上方粘贴图标会随着背景一起滑动，需要修改一下。

/* themes/Hugo-theme-next/assets/css/_common/scaffolding/highlight/copy-code.scss */
.highlight {
    position: relative;
}

当代码块没有指定语言时，样式可能和指定了语言的不同，因为原本只有 div.highlight 是有 css 规则的。我修改了一下将所有 pre 元素都应用规则。

图片

去掉了图片加载的 gif 动画。

图片预览器换成了 medium-zoom，因为它比较简洁。换来换去的，现在觉得默认的 viewer 挺不错的。

为了更正 viewerjs 预览图片时 body 宽度变化，导致文字自适应伸缩的问题，需要对样式做出一些修改。viewerjs 假定了浏览器是 chrome，所以滚动条宽度是 16，并且把这个属性设置在了 body.viewer-open 的 padding-right 中。我觉得不改动 padding，而是设置 margin 会合适一些。

使用 viewerjs 时滚动条的宽度也是个问题，首先有些较短的页面不一定会有滚动条，其次 Firefox 的滚动条宽度是 0。添加 css 如下：

:root {
    --custom-viewer-open-padding-r: 0px;
    --custom-viewer-open-margin-r: 17px;
}

body.viewer-open {
    padding-right: var(--custom-viewer-open-padding-r) !important;
    margin-right: var(--custom-viewer-open-margin-r) !important;
}

然后加一个 js 脚本：

document.addEventListener("DOMContentLoaded", () => {
  let width = window.innerWidth - document.body.clientWidth;
  if (width > 0) {
    width += 0.5;
  }
  document.documentElement.style.setProperty(
    "--custom-viewer-open-padding-r",
    "0px"
  );
  document.documentElement.style.setProperty(
    "--custom-viewer-open-margin-r",
    `${width}px`
  );
});

预览的背景我也改了一下：

/* viewerjs 改背景为模糊效果，这样黑暗模式也看得清 */
.viewer-container {
    backdrop-filter: blur(10px);
}

2024 年 8 月 31 日：觉得 viewerjs 的动画太慢了，现在又换成了简单的 medium-zoom 了。上面的复杂操作也不用做了。

CDN

修改配置选项为 cdnjs，避免国外网络访问慢（毕竟都是架在 GitHub 上了）。

数学公式

为了自定义内联数学公式的渲染样式，根据 issue 90 下的评论，在 themes/Hugo-theme-next/layouts/partials/head/style.html 中加入：

<!-- 解决 $行内公式$ 无法渲染 -->
<script type="text/javascript" id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js">
</script>
<script>
  MathJax = {
    tex: {
      displayMath: [['$$', '$$'], ['\\[', '\\]']],
      inlineMath: [['$', '$'], ['\\(', '\\)']]
    },
    svg: {
      fontCache: 'global'
    }
  };
</script>

同时，在配置文件中正确开启 passthrough：

markup:
  goldmark:
    extensions:
      # 如果使用了 MathJax，需要用同样的 delimiters 参数开启 passthrough
      passthrough:
        enable: true
        delimiters:
          block: [['$$', '$$'], ['\[', '\]']]
          inline: [['$', '$'], ['\(', '\)']]

处理 markdown 文件的相对链接

指向 markdown 的链接重定向到 html 页面的功能是通过 layouts/404.html 里的脚本改写 URL 完成的，需要和配置中的 uglyURLs 选项配合使用。加载的旋转效果是则从网上抄的。

现在关闭了 uglyURLs，仍然使用相对路径，图片和路径的渲染参考了 这个帖子。但是路径仍然可能出现 URI 转义的问题，所以 layouts/404.html 还是在用。

现在 404.html 留着备用，但是图片和链接转换都通过 Hugo 的钩子来实现相对路径转绝对路径。

1. 因为使用了 pretty URLs，所以每个相对路径前面要额外加上 ../ 退到上一级。
2. 要在配置文件中配置 disablePathToLower 为 true。这样一个文章的链接就会包含大小写。
3. 处理相对路径时，不能用 .Page.Path，要用 .Page.RelPermalink，前者是全小写的。

为什么要允许路径包含大小写？因为非文章的资源文件会按照其文件夹原名组织，如果这一路上有大写字母就会导致相对路径引用不到资源。

搜索框

在 Firefox 上面没有问题，但是在 Chrome 上会出现框中有文字时，下方出现横向滚动条的情况。小修了一下 css，加大了 margin-right。

Robots.txt

从国外网站和小红书的都抄来了一段。

文章摘要

见 Hugo 文章摘要。