Zhi 主题 v0.2.0：多语言切换 + 文章系列 + Mermaid 升级

Zhi 主题 发布了 v0.2.0——这是从 4 月份 初次发布 后最重要的功能更新。这次发布的三个重头功能——多语言切换、文章系列（Series）分类法、Mermaid v11+ 升级——都是在自己使用过程中逐步积累的需求。

简单来说：

• 多语言切换：地球图标按钮 + CSS 下拉菜单，自动关联双语文章
• 文章系列：系列概览页（卡片布局）+ 详情页（步骤/时间线布局），支持正序/倒序切换
• Mermaid 升级：用上了 v11+ 的异步 API，暗色模式自动适配
• 还有一系列 Bug 修复和文档更新

下面逐个介绍。

多语言 / i18n 支持

使用场景

博客一直是中英双语的，之前靠的是 Hugo 内置的多语言机制：每篇文章维护 .md（中文）和 .en.md（英文）两个文件，URL 路径自动区分 /zh/ 和 /en/。这本身没问题，但缺一个关键的交互——读者找不到语言切换的入口。

Hugo 的多语言支持做得很好，但主题侧需要自己实现 UI。大部分 Hugo 主题提供的是简单的下拉选择器，但在这个博客的场景里，还有一些特殊的约束：

1. 系列（Series）在不同语言下使用不同的分类名——中文叫"eBPF 可观测性系列"，英文叫"eBPF Observability Series"
2. 归档页面的 slugs 在不同语言下不一样
3. 切换语言时最好能保留当前阅读的页面，而不是弹回首页

实现方案

v0.2.0 的主题在头部加了一个地球图标按钮。点击展开一个 CSS 下拉菜单，列出当前页面的所有翻译版本。

核心实现依赖 Hugo 原生的 .Page.Translations 方法——它会自动在当前站点的其他语言中查找同 slug 的页面。对于系列页面这类特殊场景，主题做了额外处理：通过文章的翻译链反向关联不同语言下的系列分类术语页。

使用上非常简单——只要你的站点配置了 2+ 种语言，按钮就会自动出现。主题自带了 en.toml 和 zh-cn.toml 两份翻译文件，覆盖了头部、侧边栏、页脚、阅读进度等所有 UI 元素。

语言切换按钮自动处理了边界情况：当前语言不显示在菜单中、单语言站点不显示按钮、键盘可访问。

文章系列（Series Taxonomy）

为什么需要这个功能

博客里有些专题是跨分类的——比如"eBPF 可观测性系列"有 6 篇文章，分布在"可观测性技术"和"架构与设计"两个分类下。光靠分类和标签，读者没法按顺序看完一整系列的内容。

Hugo 从 v0.90 开始支持自定义分类法（taxonomies），理论上可以用 series 做分类。但主题侧需要完整的 UI 支持才真正可用。

系列概览页

/series/ 页面以卡片布局展示所有系列。每个卡片显示系列封面图、名称和文章数量。

系列详情页

点击任一系列，进入详情页。布局是步骤/时间线（stepper）风格——每篇文章显示为一个步骤节点，带有编号、标题和摘要。

默认按权重逆序排列（最新的在前面），方便新读者看到系列的全貌。右上角有一个排序切换按钮，可以切换为正序（阅读顺序）。用户偏好通过 localStorage 持久化——下次访问同一个系列时，记住你上次的选择。

在文章底部，系列内的文章也会显示"上一篇/下一篇"导航，方便连续阅读。

使用方法

在文章 front matter 中添加 series 和 weight：

1
2
3
4
5
6
7

---
title: "eBPF 可观测性入门"
date: 2026-06-10
weight: 1
series:
  - "eBPF 可观测性系列"
---

weight 控制系列内的排序。用 weight 而不是 date，好处是可以在系列中间插入新文章，不需要改其他文章的日期。比如你想在第三篇和第四篇之间加一篇文章，把它的 weight 设为 3.5 即可。

关于双语系列的命名：中文文章用中文系列名，英文文章用英文系列名。Hugo 会把它们视为两个独立的分类词条，各自显示对应语言的文章列表。主题会自动通过文章的翻译链来关联它们。

Mermaid v11+ 升级

博客里用 Mermaid 画架构图比较多（示例文章）。

v0.2.0 的升级点：

1. 异步渲染 API：Mermaid 从旧的同步 init() 切换到了新的 mermaid.run() / mermaid.render() 异步 API，与 Mermaid v11+ 保持一致
2. 暗色模式适配增强：自动修正浅色节点的文字颜色，使用 HSL 变暗算法来覆盖 classDef 的 !important 规则——这样即使节点定义了亮色背景，切换到暗色主题时文字仍然可读
3. 支持的图表类型扩展：完整支持 v11+ 的新图表类型——architecture、kanban、block-beta、mindmap 等

对于内容创作者来说，升级是透明的：你不需要改任何文章内容，所有 Mermaid 图表自动享受新版本的渲染效果。

细节改进与 Bug 修复

v0.2.0 还有一些不那么显眼但很实用的改进：

首页排序修复：之前有个棘手的 bug——系列文章的 weight 字段"泄漏"到了首页和列表页的排序中。如果你的 post A 设了 weight: 1（表示系列第一篇），首页会把它排在所有文章之前，不管它的日期是多少。修复后首页始终按日期倒序排列，weight 只在系列详情页生效。

代码渲染增强：改进了代码块的渲染管线，解决了几个边缘情况——嵌套 ``` 符号、行号对齐、复制按钮在长行场景下的行为。

图片溢出：系列摘要中的图片设置了 max-width: 100%，防止图片超出卡片边界。

SEO 优化：使用 Language.Locale 替代弃用的 LanguageCode，修复了多语言站点在搜索引擎中的语言标记问题。

文档全面更新：为所有新功能编写了中英文双语文档，新增了"语言切换"、“系列”、“多语言/i18n"等章节。

更新方式

如果你已经在用 Zhi 主题，更新非常简单。主题作为 git submodule 引入，只需要拉取最新的 tag 并更新 submodule 指针：

1
2
3
4
5

cd themes/hugo-themes-zhi
git checkout v0.2.0
cd ../..
git add themes/hugo-themes-zhi
git commit -m "chore: update theme to v0.2.0"

配置调整

v0.2.0 新增了 series feature flag，启用后在站点的 config.yaml 中添加：

1
2
3
4
5
6

params:
  features:
    series: true    # 启用系列功能

taxonomies:
  series: series    # 注册 series 分类法

多语言切换不需要额外配置——站点有 2+ 种语言时自动启用。如果不想显示切换按钮，在站点配置中只保留一种语言即可。

主题模块方式（可选）

如果你的站点使用 Hugo Modules 引入主题，更新依赖的 commit hash：

1
2
3
4

[module]
  [[module.imports]]
    path = "github.com/mickeyzzc/hugo-theme-zhi"
    ref = "v0.2.0"

然后运行 hugo mod tidy。