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

> Oink 0.6.0 为现有博客外壳增加沉浸式呈现，用题图、作者、系列、三种索引形态和分享条 补全博客发布能力，并以安全告警取代会中止整个构建的模板错误。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

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

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

**v0\.6\.0 · 2026-08-20**
- [查看发布](https://github.com/pgsty/oink/releases/tag/v0.6.0)
- [源码 · tar\.gz](https://github.com/pgsty/oink/archive/refs/tags/v0.6.0.tar.gz)
- [源码 · zip](https://github.com/pgsty/oink/archive/refs/tags/v0.6.0.zip)
- [pgsty\/oink](https://github.com/pgsty/oink)

## 概览 {#at-a-glance}

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

## 沉浸式博客呈现 {#article-shell}

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

```yaml
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`。

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

## 博客补完 {#blog}

### 题图 {#featured-image}

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

| 模式 | 呈现 |
| --- | --- |
| `none` | 不渲染文章题图；默认值 |
| `banner` | 标题上方的 16:9 带框题图 |
| `wash` | 低不透明度铺在文章头部背后 |
| `hero` | 博客页面的全幅背景 |

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

### 作者 {#authors}

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

### 系列 {#series}

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

### 三种索引形态 {#blog-index}

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| `ui.blog_index` | `list` | `list`、`cards` 或 `table` |
| `ui.blog_index_columns` | `3` | 卡片列数 |
| `ui.blog_index_size` | `12` | 列表/卡片每页文章数 |
| `ui.blog_index_toggle` | `false` | 读者侧三形态循环切换 |

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

### 分享 {#share}

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

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

## 页面标注 {#annotation}

`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` 退出。

## 告警替代预览宕机 {#warn-not-stop}

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

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

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

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

## 大纲轨道 {#outline}

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

## 修复与精简 {#fixed}

- 挂载内容不再把构建机路径写入编辑、历史或新建子页链接。
- `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 支持范围保持不变。

## 配置 {#configuration}

| 键 | 默认值 | 说明 |
| --- | --- | --- |
| `ui.featured_image` | `none` | `none` / `banner` / `wash` / `hero` |
| `ui.toc_style` | `fixed` | `fixed` / `flow` |
| `ui.toc_taxonomies` | `true` | 是否在右轨显示分类词云 |
| `ui.blog_index` | `list` | `list` / `cards` / `table` |
| `ui.blog_index_columns` | `3` | 卡片列数 |
| `ui.blog_index_size` | `12` | 列表/卡片分页大小 |
| `ui.blog_index_toggle` | `false` | 读者侧三形态切换 |
| `ui.share` | `[]` | 有序分享目标 |
| `ui.translation_notice` | `false` | 可选的权威语言 |
| `time_format_blog` | `2006-01-02` | 默认值有变更 |
| `time_format_default` | `2006-01-02` | 默认值有变更 |

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

## 迁移 {#migration}

从 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`。

## 验证 {#verification}

0.6.0 正式版经过以下验证：

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

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

## 完整变更集 {#full-change-set}

[v0.5.0 到 v0.6.0](https://github.com/pgsty/oink/compare/v0.5.0...v0.6.0)