# 升级到 Oink 0.4.0

> 把 Oink 0.3.x 站点升级到统一的场景组件版本，并检查翻页、导航栏、页脚、键盘与输出变化。

---

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

---

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

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

## 1. 固定不可变版本 {#pin-release}

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

```sh
hugo mod get github.com/pgsty/oink@v0.4.0
hugo mod tidy
hugo mod graph | grep github.com/pgsty/oink
```

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

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

## 2. 检查新的默认行为 {#review-defaults}

### 顺序翻页 {#pager}

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

```yaml
---
pager: false
---
```

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

### 全站顶部导航栏 {#navbar}

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

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

```yaml
cascade:
  navbar_enabled: false
```

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

### 全站页脚 {#footer}

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

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

### 键盘与页面操作 {#keyboard-and-actions}

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

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

## 3. 替换已移除的页脚参数 {#footer-parameters}

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

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

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

```yaml
# 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. 有意识地启用数学公式 {#mathematics}

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

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

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

## 5. 只在需要时采用场景 {#adopt-scenarios}

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

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

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

## 6. 执行升级矩阵 {#validation}

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

| 表面         | 检查内容                                           |
| ------------ | -------------------------------------------------- |
| 文档/Book    | 侧栏顺序、翻页、head 关系、标题、页面操作          |
| 博客         | 时间顺序翻页、RSS 归属、顶部导航栏、页脚           |
| Landing/首页 | 无 JS 内容、紧凑菜单、减少动态效果、打印、本地事实 |
| 版本发布     | 推导 URL、完整校验和、待发布/已发布行为            |
| Book print   | 章节顺序、唯一 ID、本地 xref、跳过 `no_print` 页面 |
| 无障碍       | 纯键盘、焦点顺序、两种主题、强制颜色               |
| 部署         | 站内链接与资产保留 base path 前缀                  |

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

```sh
npm test
npm run test:browser
```

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

## 安全回退 {#rollback}

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

完整功能与行为摘要见 [0.4.0 发布注记](/zh/blog/release/0.4.0/)。