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

Oink 0.4.0 在一个合并发布中交付连续阅读与发布界面、可复用 Landing 页面、 带稳定引用的 Book 出版能力，以及键盘优先的站点外壳。
撰文： OINK 维护者 |
分类:
标签:

发布日期：2026-08-14 · 已签名主题标签： v0.4.0 · 代码仓库： 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 输出会保留理解对应界面所需的完整内容。

版本亮点

阅读与发布

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

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

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

完整契约见顺序阅读与数学公式和版本发布与下载。

Landing 页面

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

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

数据解析、全部 21 种分区、本地事实规则与输出矩阵见 Landing 页面。

Book 出版

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

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

创作与迁移契约见 Book 出版。

键盘与站点外壳

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

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

参见键盘导航与导航与菜单。

兼容性与行为变化

  • 最低支持版本仍为 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

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

消费站检查清单见本站的 0.4.0 升级指南；主题仓库保留冻结的 PRD 5 迁移参考。

验证

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

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

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

完整变更集

完整源码差异见 v0.3.0 到 v0.4.0。

最后修改 2026年8月14日 · chore: update site to OINK v0.4.1 (911d6a9)