Oink 0.6.0：沉浸式博客、更稳健的构建、更精简的内部实现

OINKOINK 项目本身作为正式发布注记与项目公告的作者。

Oink 0.6.0 保留 0.5 确立的组件 API，集中改进它周围的系统：长文阅读、博客发现、 来源标注、版本发布、构建韧性，以及主题自身的可维护性。

本版本没有新增 article 类型，也没有第二套页面外壳。沉浸式阅读只是现有博客外壳的 一种配置，因此文章仍处于原有列表、订阅源、分类、系列与翻页序列中。

概览

• 博客外壳新增全幅 hero 题图和随正文起步的流式大纲轨道。
• 博客发布新增作者主页与署名、系列顺序、列表/卡片/表格三种索引，以及本地优先分享条。
• 引入页面与译文可选用经过校验的来源标注。
• 主题不再调用 errorf：普通预览告警并安全降级，发布构建继续由 --panicOnWarning 严格把关。
• 发布信息收敛为一个 release_url，不再重复维护一张事实表。
• 重复模板计算、页面 bundle 和测试构建显著减少；Font Awesome 等公共创作资产不做裁剪。

沉浸式博客呈现

沉浸式页面由四个相互独立的 front matter 键组成：

featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

把同样的键放入栏目 cascade，即可作用于其中的文章。若栏目索引本身也要采用这种呈现， 还应在栏目自己的 _index.md 上声明一次，因为 cascade 不作用于声明它的页面。

hero 把解析后的题图铺在开篇背后，并在正文开始前渐隐。常规导航栏仍然可用， 叠在图片上时带有渐隐蒙版。toc_style: flow 让大纲从正文起点开始，滚动后再吸附； toc_taxonomies: false 则移除轨道中的分类词云。 博客外壳默认不显示面包屑；需要时可在页面或 cascade 中设置 breadcrumb: true。

这些开关可以独立使用。没有图片时回到普通开篇；没有大纲且关闭词云时不渲染空轨道。 页面的博客归属与输出格式均不改变。

博客补完

题图

params.ui.featured_image 与页面键 featured_image 支持：

所有模式都复用列表缩略图与社交元数据使用的代表图片解析器。没有图片是合法状态， 非 HTML 输出继续保留静态、接近源码的形态。

作者

声明 taxonomies: {author: authors} 即可启用。作者 term 页就是作者主页： 标题是姓名，摘要与正文是简介，代表图片是头像。文章通过 authors: [vonng, oink] 指定作者，书写顺序会被保留。未使用该 taxonomy 时， 旧的 author: 字符串仍作为兼容回退。

系列

声明 taxonomies: {series: series} 即可启用。文章通过 series 加入一个或多个系列， 并可设置 series_weight。带权重的成员按权重升序排列，未加权成员随后按日期升序排列。 文章条带与系列 term 页共用同一个解析器，因此篇次与归档顺序不会漂移。

三种索引形态

列表与卡片共用年份分组与分页。单独发布的表格是完整、不分页的归档；开启读者切换后， 三种形态共用当前分页切片，不会在每个分页页重复整张归档。配置决定首屏形态， 本地偏好可以覆盖它。

分享

params.ui.share 是一个有序列表，可选 x、bluesky、mastodon、 facebook、linkedin、reddit、hackernews、telegram、 whatsapp、line、pinterest、weibo、chatgpt、claude、 email、copy。默认空列表；share: false 可关闭某一页。

分享条只使用平台意图链接与本地复制动作，不加载平台 SDK、iframe、计数器或第三方样式。

页面标注

upstream_link 是每页的来源 URL。配套事实包括 upstream_name、 upstream_copyright、upstream_license、upstream_notice、 upstream_ref 与 upstream_modified，可来自站点参数、data/upstreams 条目或 front matter。

事实不完整、许可证未知、URL 不安全或类型错误时，主题会告警并省略整行标注； 严格构建会拒绝该告警。upstream_link: "" 可让某页明确退出继承的来源标注。

params.ui.translation_notice 可选地指定权威语言。主题不会把它强加到页面 front matter 中；原生撰写的页面可用 translation_notice: false 退出。

告警替代预览宕机

主题中已经没有 errorf 调用。简单标量由 validate.html 统一校验， 组件自身的记录与标记仍由最了解它们的代码校验。

非法输入遵循同一条规则：

1. 告警并说明坏值以及安全回退或省略方式；
2. 不输出不安全、错误或容易误导的结果；
3. 普通 hugo server 继续工作；
4. --panicOnWarning 在 CI 与发布阶段阻止构建。

这样既保留严格门禁，也不会让单页笔误拖垮所有预览 URL。

大纲轨道

大纲在同一条 SVG 路径上显示可见范围与当前光标。光标携带 aria-current="location"；在减少动画或不支持注册属性的浏览器中， 它会安全回退，不会与高亮线脱节。

修复与精简

• 挂载内容不再把构建机路径写入编辑、历史或新建子页链接。
• data-* 与 aria-* 取值统一由一个 HTML 转义器输出。
• Algolia 凭据不完整时，不再渲染容器、CSS 或 JavaScript。
• Draw.io 只在页面存在 PNG/SVG 候选图时加载，同一 URL 只检查一次。
• 页面动作、翻页状态、语言目标与栏目子页按页面或站点复用结果，不再反复扫描全站。
• 不依赖语言的 feature bundle 可在不同语言页面之间共享。
• Fields 锚点由字段名派生，并在页内保持唯一。
• 打印聚合为标题与脚注增加命名空间，而常规页面 ID 不变。
• 非法输入 checker 把等价案例合并后，内容组件阶段启动 Hugo 的次数从 160 次降至 6 次， 同时保留每一条告警与回退断言。
• 已删除过期 CSS、i18n 键、废弃的独立 Article 外壳产物、重复 checker 代码和叙事式代码注释； 完整的 Font Awesome 支持范围保持不变。

配置

默认 shell 与 pager 类型列表在适用处仍由 docs、book、blog、swagger 组成，没有新增 article 类型。

迁移

从 0.5 升级时：

1. 若不希望使用 ISO 日期，请保留显式的本地化日期格式。
2. 确认发布命令带有 --panicOnWarning。
3. 把旧 release map 改为 release_url: https://github.com/<owner>/<repo>/releases/tag/<tag>。
4. 把 upstream_attribution 改为 upstream_link， 把 downstream_modified 改为 upstream_modified。
5. 不要把内容迁移为 type: article，请使用上文的博客呈现键。

迁移工具只自动处理 content Markdown 与受支持的 YAML front matter； 站点配置映射仍由维护者明确完成。从 0.4 升级时，继续执行既有顺序： report、migrate --write、check。

验证

0.6.0 正式版经过以下验证：

• Hugo Extended 0.160.1 与 0.164.0；
• 40 个 HTML/打印/Markdown/RSS/LLMS Golden；
• 85 个迁移测试与 38 个浏览器运行时测试；
• 严格示例站、Hugo Module、system 字体、旧字体覆盖与非法配置构建；
• 双语项目站构建及其非浏览器回归；
• 代表性大站性能测量与真实 EN/ZH 浏览器检查。

本地验证、提交、打标签、推送、消费站锁定与部署仍然是不同的发布状态。

完整变更集

v0.5.0 到 v0.6.0