升级到 Oink 0.4.0

Oink 0.4.0 是统一交付的场景组件版本。Reading & Release、Landing 与 Book 最初按 0.4、0.5、0.6 三条路线设计，但全部随单一公开标签 v0.4.0 发布。不要固定那些历史设计编号。

普通 Docsy 兼容内容、既有首页数据与模块路径保持兼容。升级工作主要是检查新的默认外壳行为，并替换两个已移除的 ICP 专用页脚参数。

1. 固定不可变版本

创建升级分支并更新 Hugo 模块：

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo mod graph | grep github.com/pgsty/oink

模块图必须解析到 github.com/pgsty/[email protected]，而不是伪版本或 main。Oink 0.4.0 要求 Hugo Extended 0.160.1 或更新版本，消费站仍然不需要 Node.js、PostCSS 或 CDN 流水线。

通过同级 checkout 开发时，请记住 go.work 会覆盖公开模块固定。把发布依赖判定为已验证前，应同时使用 GOWORK=off 与 HUGO_MODULE_WORKSPACE=off 单独验证公开标签。

2. 检查新的默认行为

顺序翻页

docs、book 与 blog 现在默认带顺序翻页。文档和 Book 沿可见侧栏树前进，博客沿时间顺序前进。页面或分区刻意不属于任何序列时，可以退出：

---
pager: false
---

如果站点根手册已经使用 params.ui.docs_root: home，请确认翻页与侧栏遍历同一棵预期内容树，不要另建翻页清单。

全站顶部导航栏

顶部导航栏现在显示在所有布局中。紧凑状态只保留一行图标导航，不再有第二套移动端手风琴菜单。请移除依赖独立移动菜单的本地脚本或测试；navbar_accordion_single_open 已弃用并会被忽略。

要保留一个刻意不显示 navbar 的分区，请使用经过校验的覆盖：

cascade:
  navbar_enabled: false

站点设置位于 params.ui.navbar_enabled；分区 cascade 与页面 front matter 则使用顶层 navbar_enabled 键。三处都只接受布尔值，并且离当前页面最近的值优先。

全站页脚

footer_style 默认为 fat，现在作用于所有布局，只接受 fat、slim 或 none。data/home/<language>.yaml 中的旧页脚数据保持兼容，但现在会显示在全站，而不只是首页；方便时请迁移到 data/footer/<language>.yaml。

读者可以折叠 fat 页脚的链接网格，选择会保存在本地。只保留 bottom bar 时使用 slim；需要移除某页或某分区页脚时使用 none。

键盘与页面操作

文档、博客与 Swagger 外壳默认启用单键导航。/ 现在打开完整搜索，\ 打开纯命令模式。请检查所有仍然描述旧 / 行为的培训文字或自定义脚本。

页面操作已经迁移到面包屑旁的拆分按钮。请移除针对旧 TOC 栏折叠操作组的本地 CSS 或浏览器测试。完整按键契约见键盘导航。

3. 替换已移除的页脚参数

Oink 不再读取 ICP 专用参数对：

# 0.4.0 之前
params:
  footer_icp: 京ICP备00000000号
  footer_icp_url: https://beian.miit.gov.cn/

请改成一个支持行内 Markdown 的字符串：

# Oink 0.4.0
params:
  footer_center_info: '[京ICP备00000000号](https://beian.miit.gov.cn/)'

显式空字符串会隐藏中间区域；省略时默认显示 Powered by Oink。Docsy 的 params.copyright 字符串/Map 契约与 Hugo 顶层 copyright 回退保持支持。

4. 有意识地启用数学公式

内容使用 \(...\)、\[...\] 或 $$...$$ 时，应在消费站启用 Goldmark passthrough，因为 Hugo 不会合并主题 markup 配置：

markup:
  goldmark:
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]

主题负责渲染钩子与本地 KaTeX 资产。单独设置 math: true 不是启用开关。既有无参数 eq 保持有效且不编号；只有带引号的 num 才会选择 Book 形式。

5. 只在需要时采用场景

普通内容不要求转换，可以逐步引入更严格的模型：

• 顺序阅读已经默认启用，只需配置例外与导航根。
• 版本发布与下载用本地事实替代重复复制的发布 URL、校验和与安装命令。
• Landing 页面用于替换专用全宽模板，或新的 Docsy block 短代码组合；既有首页数据保持兼容。
• Book 出版需要显式采用。转换前先盘点既有 ID、题注、引用与输出要求。

旧 home/ partial 名称仍是轻量兼容适配器，Docsy block 短代码也继续渲染。它们属于兼容路径，不是新 Landing 页面的推荐基础。

6. 执行升级矩阵

分别从生产 base URL 与子路径预览构建每种语言和输出。至少检查：

本站的完整消费站门禁是：

npm test
npm run test:browser

其他站点应运行等价的构建、链接、输出、无障碍与浏览器检查。本地构建成功不能证明已签名标签、公开模块缓存、线上部署或 CDN 状态；每一层都应单独记录。

安全回退

如果站点特定迁移失败，请在 go.mod 中恢复上一固定版本并重新构建。不要把删除已写内容或重置工作树当作回退捷径。保留升级分支与验收证据，才能在不丢失无关工作的前提下修正失败契约。

完整功能与行为摘要见 0.4.0 发布注记。