26 September 2026, 16:30 (GMT+8)

2026年09月26日 16:30（东八区 / 北京时间）

网站引擎升级：Zola 0.23.6 + Ametrine tera2 迁移完成 · 看板/归档/热力图修复

概述

本轮把整站从「Zola 0.22 时代」推到 Zola 0.23.6 + Ametrine tera2，并顺手修掉三处长期不舒服的地方：

1. 引擎与主题升级：主题子仓库由 main 切到同仓库的 tera2 分支，适配 Tera 2；
2. 模板全量迁移：旧语法（宏导入、宏调用、shortcode、concat 过滤器）逐条改写为新语法，zola build 重新跑通；
3. 功能修复：看板界面恢复渲染与编辑、归档剔除无标题的空链接、热力图支持月初标记与悬浮日期。

一、为什么要换到 tera2

Zola 0.23.6 内置的模板引擎已经是 Tera 2，它删掉了一批我们一直在用的老写法：

结论：只升级 Zola 不动主题，整站会在第一个模板处就编译失败；旧主题 main 与新引擎不兼容，所以必须用为重写而生的 tera2。

二、子仓库与构建环境

• themes/ametrine：main → tera2（f125214），嵌套的 icons 子模块同步到 859c0e7；
• .gitmodules: 增加 branch = tera2，子仓库自身的 branch.<name> 也指向 tera2，以后 git submodule update --remote 会跟着 tera2 走；
• 本地 zola --version = 0.23.6，主题要求 min_version = 0.22.1。

# 切换并拉取子仓库新分支
git -C themes/ametrine fetch origin --prune
git -C themes/ametrine checkout -B tera2 origin/tera2
git -C themes/ametrine submodule update --init --recursive

# 构建
zola build          # 或 ./build-site.sh（含加密同步 + 后置校验）

三、站点侧迁移清单

• 宏 → 组件：article_list、kanban、kanban_list、nanolog_list、music_player、badges、beeper、now_playing、online、design、design_app 等模板里的宏调用全部换成 {{ <icon …/> }}；
• 导入 → 直接包含：basb.html 原本通过宏渲染 basb_list.html，改为设置变量后 {% include %}；
• 未使用的宏文件 → 组件：templates/macros/encryption.html（早已没人调用）拆成 templates/components/ 下 3 个组件：is_encrypted_page、payload_data_path、page_encrypt_enabled；
• 区块 shortcode → 组件：10 个板块首页的 ASCII 电子屏横幅由 {% crt(label=…) %} 改为 {% <crt label="…"> %}；
• 过滤器替换：archive.html、heatmap_component.html、kanban_heatmap_component.html、article_list.html 的 concat 改成展开语法；age.html 的 as_str/slice 改成字符串拼接 + 数组切片；games.html 的 filter(attribute=…) 改成循环筛选；
• Tera 2 更严格的两点：
  • 子模板顶层只能出现 extends / block / component，index.html、basb.html、404.html 里游离的 HTML 与注释被收进区块；
  • 访问可能不存在的字段要写成可选链，例如 page.extra.encryption?.encrypt、paginator?.pages；
• 文档型文章：模板速查、v1.0 发布说明、4 篇 nanolog、CMake 文章里用来演示的模板代码，统一改成 Tera 的 raw 区块包裹（避免示例被当成真模板执行），页面展示内容保持不变。

四、主题侧修复（tera2 仍属预发布状态）

tera2 分支自带两处小毛病，已在本地补齐（后续若更新子仓库需重新打补丁，建议同时上报上游）：

1. templates/partials/head.html：[...styles, page.extra.styles] 这类写法在 Tera 2 里是「把数组塞进数组」，会导致每页/每板块的 styles、scripts 渲染成 /[ kanban style.css"] 之类的乱码路径 —— 这正是看板页 CSS/JS 全都没加载、界面只有裸骨架的根因。已改为展开 + 字符串兼容写法；
2. templates/partials/header.html：404 页没有 section 变量，section.generate_feeds 会直接抛错，已改为 section?.generate_feeds。

五、本轮功能修复

5.1 看板（/kanban/）

• 界面恢复渲染：资源路径修好后，kanban/style.css 与 4 个看板脚本正常加载，卡片布局与进度条恢复正常；
• 默认月份不再是空窗：以前默认选中「当前月」，当月还没写看板时列表一片空白；现在当月没有看板会自动回退到最近一个有看板的月份，并支持年 / 月下拉切换；
• 空态提示：选中的月份确实没有看板时，列表区给出「该月暂无看板，可切换月份或点击 ＋ 新建看板」的提示，而不是留白；
• 新建看板可触发：＋ 新建看板 按钮正常出现并打开 GUI 编辑器（看板信息、列、卡片、重要等级、背景色、Markdown 预览、生成并复制、Token 同步）；
• 编辑看板可用：左上角站点图标连点 6 次进入管理员模式后，卡片右上角 ✎ 编辑 出现，点击即带入该看板的原始 Markdown 进入「修改」模式。

5.2 归档（/archive/）

• 弄清「无目标文章链接」的成因：归档列表之前把 nanolog 的文章也一起聚合了，而 nanolog 正文没有 title 字段（标题由时间生成），于是渲染出一堆只有日期、点进去也不知道是什么的空链接；
• 修复：归档范围收缩回既定板块（英语、数学、分享、写博客、工程、Debug），不再收录 nanolog；同时给标题加上兜底（无 title 时退回 slug 或「（无标题）」），保证每条明细都有章节名。

5.3 热力图（归档页 / 文章页 / 看板页）

• 月初标记：每月 1 号的格子上加了一个金色圆点 + 描边（看板年视图里是「包含 1 号的那一周」），一眼能看出月份分界；
• 悬浮看日期：所有格子（包括没有文章的空白格）悬浮都会显示 年-月-日，有文章时附加篇数与标题，月初再加「月初」提示；
• 空白格改用 aria-disabled 而不是 disabled，这样禁用状态的格子也能响应悬浮提示。

六、验证

zola build                     # 通过：272 个 HTML 页面
node scripts/verify-kanban-build.mjs   # 通过：5 个看板周页与列表卡片一致

• 浏览器实测：/kanban/ 卡片显示、＋ 新建看板 打开编辑器、管理员模式后 ✎ 编辑 带入原文、Markdown 生成与复制正常；
• /archive/ 共 55 条明细，0 条 nanolog、0 条空标题，热力图 12 个月均有月初标记；
• 文章页热力图（近 35 天）与看板月/年视图的月初标记、悬浮日期均已生效。

七、已知问题与后续

• tera2 仍是预发布分支，上面两处主题补丁属于本地修改，跟上游同步后需要重新打（或等上游合并）；
• 构建时仍有主题的弃用警告：4 处 get_taxonomy_url(name=…) 建议改用 term=；代码块语言 tera / git / Plaintext 未被高亮器识别（仅警告，不影响输出）；
• content/archive/_index.md 的 aliases = ["Archive"] 与真实目录 /archive/ 在 macOS（大小写不敏感）上会互相覆盖，部署到 Linux 环境不受影响；
• 归档目前已剔除 nanolog；如果之后希望 nanolog 也进归档，需要先给 nanolog 生成标题再放开。

相关链接：归档 · 周计划看板 · 映射说明 · Ametrine 主题