# Oink 0.4.0 — 面向完整发布流程的场景组件体系

> Oink 0.4.0 在一个合并发布中交付连续阅读与发布界面、可复用 Landing 页面、 带稳定引用的 Book 出版能力，以及键盘优先的站点外壳。

---

LLMS index: [llms.txt](/zh/llms.txt)

---

**发布日期**：2026-08-14 · **已签名主题标签**：
[v0.4.0](https://github.com/pgsty/oink/tree/v0.4.0) · **代码仓库**：
[pgsty/oink](https://github.com/pgsty/oink)

Oink 0.4.0 完整交付场景组件体系。原始设计将 Reading &
Release、Landing 与 Book 分别放在 0.4、0.5、0.6 三个里程碑中；公开版本将三条轨道合并到一个已签名的
`v0.4.0` 标签，让消费站接入一套连贯契约，而不是一串彼此依赖的预览版本。

本版本继续保持本地优先：消费站仍然只需 Hugo
Extended 与 Go，不需要 Node.js、浏览器端 API 或 CDN。所有交互都采用渐进增强；HTML、打印、Markdown 与 RSS 输出会保留理解对应界面所需的完整内容。

**v0\.4\.0 · 2026-08-14**
- [查看发布](https://github.com/pgsty/oink/releases/tag/v0.4.0)
- [源码 · tar\.gz](https://github.com/pgsty/oink/archive/refs/tags/v0.4.0.tar.gz)
- [源码 · zip](https://github.com/pgsty/oink/archive/refs/tags/v0.4.0.zip)
- [比较变更](https://github.com/pgsty/oink/compare/v0.3.0...v0.4.0)
- [pgsty\/oink](https://github.com/pgsty/oink)

## 版本亮点 {#release-highlights}

### 阅读与发布 {#reading-and-release}

文档、Book 与博客页面现在拥有连续阅读 Pager，其顺序来自读者在侧栏看到的同一棵扁平导航树。上一页和下一页也会作为同源
`rel`
元数据写入文档头。显式导航数据、纯链接条目、侧栏分组和博客时间顺序仍保留各自语义，不会意外变成阅读目的地。

数学公式可以通过 Goldmark
passthrough 使用主题内置的本地 KaTeX 渲染器。暂时无法启用 passthrough 的站点，可以使用严格、无参数的
`eq` 逃生舱渲染块公式；只有显式提供 `num`
时，同一短代码才进入 Book 的编号公式模式。

发布页面可以从本地 front
matter 渲染发布事实、发布卡片、校验和与资产清单，无需浏览器查询 GitHub。经过验证的
`data/download/<key>.yaml` 模型同时供 `download`
短代码与 Landing 下载分区使用，区分滚动渠道、固定版本渠道与明确的待发布状态。

完整契约见[顺序阅读与数学公式](/zh/docs/scenarios/reading/)和[版本发布与下载](/zh/docs/scenarios/releases/)。

### Landing 页面 {#landing-pages}

数据驱动的首页渲染器现在也是普通页面可用的 `layout: landing`
外壳。页面可以使用内联数据，或从 `data/landing/<key>/`
读取带语言回退的记录，再组合 21 种内置分区，包括价格、对比表、命令框、步骤、时间线、代码面板、案例、下载与条形图。

所有事实都在构建时留在本地。揭示、数字递增、复制、主题图片和紧凑菜单等可选行为只在 Landing 页面需要时加载。关闭 JavaScript 后内容仍然完整；跑马灯可以因焦点或用户选择暂停，遵守 reduced
motion，并向辅助技术隐藏重复轨道。

数据解析、全部 21 种分区、本地事实规则与输出矩阵见
[Landing 页面](/zh/docs/scenarios/landing/)。

### Book 出版 {#book-publishing}

长篇手册可以在既有文档外壳上声明 Book 元数据。章节获得草稿标签、当前页侧栏标题，以及语义化的
`fig`、`tbl`、编号 `eq` 与按当前语言解析的 `xref`
目标。整书图表目录与目录树复用同一套注册表。

可选的整书打印文档会把跨章节组件链接改写为文档内引用，并为重复标题 ID 加命名空间。配套迁移工具默认 dry-run、可重复执行，提供可复现的 TPME、DDIA 与 pg-internal 配方、机器可读报告、歧义跳过项，以及第二次运行零变更检查。

创作与迁移契约见 [Book 出版](/zh/docs/scenarios/book/)。

### 键盘与站点外壳 {#keyboard-and-shell}

站点外壳现在支持单键阅读导航：`w`、`s` 在侧栏移动，`a`、`d` 折叠或展开分组，
`j`、`k` 在页面大纲间移动，`q`、`e` 沿连续 Pager 翻页。`h` 切换会话级阅读模式；
`l`、`t`、`f`、`c`
分别切换语言、主题、搜索与命令界面。所有按键都会让位于编辑控件、输入法组合、按住的修饰键与已打开的对话框。

导航栏现在覆盖文档、博客、taxonomy 与 Swagger 布局，并以一个紧凑状态取代第二套移动菜单。页面操作移到面包屑行，成为以「复制 Markdown」为主操作的分裂按钮。页脚支持经过验证的
`fat`、`slim`、`none` 三种样式，读者还可以折叠胖页脚的链接网格并保留该偏好。

参见[键盘导航](/zh/docs/advanced/keyboard/)与[导航与菜单](/zh/docs/configure/navigation/)。

## 兼容性与行为变化 {#compatibility}

- 最低支持版本仍为 Hugo Extended 0.160.1。
- 模块路径仍为 `github.com/pgsty/oink`；消费站仍不需要前端工具链。
- Pager 默认作用于 `docs`、`book` 与 `blog`
  内容类型；需要退出的站点可配置明确的类型列表，或在页面设置 `pager: false`。
- `/` 现在打开完整搜索，`\` 打开纯命令模式；命令面板内部的 `>` 前缀保持不变。
- `params.footer_icp` 与 `params.footer_icp_url` 被一个行内 Markdown 值
  `params.footer_center_info` 取代；显式空字符串会隐藏中间区域。
- `params.ui.navbar_enabled` 默认为 `true`，可以在全站、section
  cascade 或单页覆盖。
- 旧首页数据与 Docsy
  block 短代码继续兼容；新的 Landing 页面应使用标准分区注册表。

## 升级到 0.4.0 {#upgrade}

1. 固定已签名标签并整理模块图。
2. 使用过 ICP 页脚参数的站点改用 `footer_center_info`。
3. 检查 Pager 默认值、`/` 与 `\` 快捷键，以及站点自己的导航栏与页脚覆盖。
4. 只有对比清楚本地差异后，才删除复制出来的主题 partial。
5. 构建有代表性的文档、博客、Landing、Book、打印、Markdown、移动端与明暗模式界面。

```sh
hugo mod get github.com/pgsty/oink@v0.4.0
hugo mod tidy
hugo --gc --minify
```

消费站检查清单见本站的
[0.4.0 升级指南](/zh/docs/upgrade/v0-4/)；主题仓库保留冻结的
[PRD 5 迁移参考](https://github.com/pgsty/oink/blob/v0.4.0/docs/prd5-migration-guide.zh.md)。

## 验证 {#verification}

已签名标签与发布主题源码指向同一提交。主题 CI 覆盖 Hugo Extended
0.160.1 与 0.164.0、32 个语言包、vendor 资产、运行时单元测试、全部 PRD
4/5/6 契约，以及零警告示例站构建。项目站固定公开标签，并覆盖双语源码、渲染 Markdown、站内链接、替代配置构建、浏览器行为与完整多语言 WCAG
AA 矩阵。

有代表性的文档站、门户、Book 与归档站也在关闭 workspace 的情况下，从公开
`v0.4.0` 模块完成构建。

源码验收、公开标签、消费站固定版本与线上部署是不同的证据门禁。发布这篇注记不能代替站点流水线完成后的线上 URL 冒烟检查。

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

完整源码差异见
[v0.3.0 到 v0.4.0](https://github.com/pgsty/oink/compare/v0.3.0...v0.4.0)。