24 June 2026, 22:00 (CST)

2026年06月24日 09:40（东八区 / 北京时间）

看板线上缺失排查 · Ametrine 子模块更新 · 新文章卡片样式

概述

本轮三件事：周计划看板本地/线上一致性排查、Ametrine 主题子模块更新到 6d1c244（New article card design）、Debug 专栏应用两种文章卡片样式。看板本地可用 zola build / zola serve；正式部署推荐 ./build-site.sh（含看板产物校验）。

1. 看板列表仅显示 1 张卡片

1.1 问题

1.2 排查流程（源码 → 构建）

阶段 A：源码

结论：源码两侧一致，问题不在 Markdown 缺失。

阶段 B：构建产物

结论：线上 gh-pages 是旧/不完整部署，并非前端 JS 把第二张卡片藏起来——HTML 里根本没有第二张卡片，明细页目录也未生成，手动输入 URL 必然 404。

1.3 根因

线上 gh-pages 某次部署产物不完整（缺少 2026-06-16/ 目录与列表第二张卡片），与本地是否使用 ./build-site.sh 无直接关系——GitHub Actions 同样只跑 zola build，看板理论上应能完整生成。部署流水线原先缺少 kanban 产物校验，异常未能被及时发现。

1.4 修复

重新部署后（GitHub → Actions → Build Zola and Deploy to GitHub Pages → Run workflow），线上应出现 2 张卡片且 /kanban/2026-06-16/ 可访问。

1.5 补充：本地为何只用 zola build / zola serve 就能完整实现看板？

日常开发若只用 zola build、zola serve，不主动跑 ./build-site.sh，看板依然完整——这是预期行为，因为看板整条链路都在 Zola 原生构建内，不依赖 build-site.sh 额外步骤。

zola build 已覆盖看板所需：

content/kanban/*.md
    ↓  Zola 读取 front matter（week_start、stats…）
templates/kanban_list.html / kanban.html
    ↓  load_data 内嵌原始 Markdown 到 HTML
static/js/kanban-*.js
    ↓  浏览器解析、渲染热力图 / Trello 看板
public/kanban/

列表页与明细页模板在构建时用 load_data 把 Markdown 写进 HTML（无需 static/kanban/ 副本）：

• templates/kanban_list.html — 每张周卡片内嵌 <textarea class="kanban-raw-source">
• templates/kanban.html — 明细页 #kanban-raw-markdown

只要 content/kanban/ 下有带 week_start 的 .md，zola build 就会生成对应页面与列表卡片；zola serve 仅本地预览 public/。

build-site.sh 在四步中，看板只依赖第 ② 步：

何时才需要 ./build-site.sh？

与「线上少一张看板」的关系（再强调）：

结论：看板 = Zola 模板 + content + static JS，zola build 已足够；build-site.sh 是站点其他能力（加密、搜索、部署校验）的包装，不是看板运行的前提。 线上问题来自 gh-pages 部署产物不完整，而非本地少用了 build-site.sh。

2. Ametrine 子模块更新

cd themes/ametrine
git fetch origin main
git checkout main && git pull
# 父仓库记录新 commit
git add themes/ametrine

主要变化：templates/partials/article_list.html 卡片布局（banner 缩略图置顶）、article_details.html 元数据分行、_article-list.scss 渐变/accent 视觉。

3. 两种文章卡片样式如何引用

Ametrine 通过 front matter 组合决定卡片形态（与 daudix 博客 一致）：

样式 A — 带横幅图（has-banner + has-accent-color）

列表卡片顶部有大图；明细页开头由 base.html 的 #banner 渲染同目录图片。

[extra]
accent_color = ["hsl(210 25% 34%)", "hsl(210 31% 53%)"]  # 浅色 / 深色各一组 HSL
banner = "banner.jpg"           # 与 index.md 同目录
banner_position = "50% 40%"     # 可选，缩略图裁剪焦点

• 图片放在文章文件夹内，如 content/…/my-post/banner.jpg
• 构建时 Zola resize_image 自动生成 WebP 缩略图

本站示例（Debug 专栏）：

样式 B — 纯 accent 渐变（has-accent-color，无 banner）

无列表缩略图；可展示 发布日 + 更新日 + 作者 等元数据行。

updated = 2026-06-21          # 与 date 不同则显示「更新」图标
authors = ["SuchaharCan"]     # 可选，显示 By …

[extra]
accent_color = ["hsl(145 22% 34%)", "hsl(145 28% 50%)"]
# 不写 banner

本站示例：

明细页横幅

只要设置了 banner，列表与明细共用同一字段；明细页无需额外模板，主题 base.html 自动在正文前插入 #banner 大图（与 daudix 一致）。

accent_color 格式

• 推荐：["hsl(H S% L%)", "hsl(H S% L%)"] — 分别为浅色/深色模式
• 也支持单字符串 "hsl(270 50% 60%)"

4. 本地验证

看板调试可直接：

zola build && zola serve

正式部署或需加密/搜索/校验时：

./build-site.sh
# 期望输出：kanban verify OK: 2 week(s), list cards match

相关链接：看板列表 · Debug 专栏 · Ametrine 主题 · daudix 博客卡片参考

5. 看板列表卡片 UI · 热力图「今天 / 本周」标记

5.1 看板周卡片（列表页）

需求： 元数据参考 Ametrine 文章详情图标盒式风格；标题以下第二、三行加粗并居中；字号随卡片高度变化；天数跨度与卡片高度的视觉区分需更明显。

模板结构（templates/kanban_list.html）：

h3 标题（左对齐 + accent 竖线）
└─ .kanban-week-body（居中容器）
   ├─ .kanban-week-meta-row  日期 / 剩余 / 进度 / 星级
   └─ .kanban-week-stats      共 N 项 · 已完成 · 待办 · 进行中
└─ .kanban-week-span-spacer  （flex 占位，不再重复叠加高度）

样式要点（sass/kanban/style.scss）：

高度 / 字号映射（SSR 与 JS 共用同一公式，static/js/kanban-rules.js → applyListCardMetrics）：

--kanban-card-body-height = 88px + 280px × (span_days / 7)
--kanban-meta-scale       = 0.85 + 0.35 × (span_days / 7)

kanban-list.js 与 kanban-heatmap.js 筛选后均调用 KanbanRules.applyListCardMetrics()，避免两套算法不一致。

CSS 变量（:root）：

--kanban-week-body-min: 88px;
--kanban-week-span-height: 280px;

若需进一步拉大/缩小高度差，优先调 --kanban-week-span-height。

5.2 热力图「今天 / 本周」标记

需求： 全年视图（周格子）与单月视图（天格子）下方，用空心三角标出当前周或当天；时区与站点一致；不破坏现有热力图样式。

时区： 读取 #kanban-week-list 的 data-timezone（来自 zola.toml → extra.timezone，当前 Asia/Shanghai），复用 KanbanRules.clockInTimezone。

显示规则：

DOM 结构：

.kanban-heatmap-week-slot / .kanban-heatmap-day-slot
├─ button.heatmap-week-cell / .heatmap-day-cell
└─ span.kanban-heatmap-today-marker   ← 仅 .is-current 时可见

样式（static/css/heatmap.css，仅作用于 Kanban 热力图）：

• 空心三角：::before 描边 + ::after 内层 --bg-muted-1 镂空，尖端朝上指向格子
• 非当前格不预留占位，避免整行高度被撑开

涉及文件：

5.3 本地验证（看板 UI + 热力图）

zola build && zola serve
# 打开 http://127.0.0.1:1111/kanban/

5.4 热力图默认选中当前年 / 当前月

需求： 进入 /kanban/ 时，右上角年份、月份下拉不再默认「最近有数据的年份 + 全年」，而是直接落在当前年、当前月（按站点时区），省去手动切换。

默认逻辑（static/js/kanban-heatmap.js → init()）：

var todayCtx = getTodayContext(siteTimezone());
var activeYear = years.indexOf(todayCtx.year) >= 0 ? todayCtx.year : years[0];
var activeMonth = activeYear === todayCtx.year ? todayCtx.month : 0;

时区： 与 §5.2 相同，读 #kanban-week-list 的 data-timezone（zola.toml → extra.timezone）。

未改动的交互： 用户手动切换年份时，月份仍会重置为「全年」（原有行为）；仅首次加载默认当前年/月。

验证： 刷新 /kanban/，右上角应显示「年份: 2026」「月份: 6 月」，热力图为按天网格，下方列表为 6 月卡片，无需再点选月份。

最后补充： 优先 使用 Codeberg中的 workflow.此处是 第一源 ，同步给 github