# OINK 1.3.1 — 阅读体验修复

> 修复 Markmap 文字与 TOC 页脚避让，为技术表格和 FileTree 注释提供显式布局选项，并升级至 Hugo 0.168 与 Dart Sass。

---

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

---

OINK 1.3.1 修复四类阅读问题，默认保留紧凑布局，同时将构建基线升级至
**Hugo Extended 0.168.0** 和 **独立 Dart Sass 1.105.2**，使用 **Go 1.27.2**
验证。CI 自动跟随 Go 和 Hugo 的最新稳定版，并记录实际版本。模块继续以
Go **1.27.0** 为最低要求。

## 阅读体验修复 {#repairs}

- **Markmap**：节点文字跟随正文颜色，在明暗模式、视觉预设和恢复读者偏好时保持
  可读；打印时保留白底深色文字。解决 [#47](https://github.com/pgsty/oink/issues/47)。
- **TOC**：固定右侧目录避让页脚，没有左侧栏的页面同样生效。标签页、博客视图切换
  和媒体加载使页脚移动时，即使没有滚动事件也会重新计算。流式目录和移动端抽屉
  保留原有布局。解决 [#49](https://github.com/pgsty/oink/issues/49)。
- **技术表格**：`.td-table--wide` 让标识符在横向滚动区域内保持可读宽度，同时约束
  长描述的宽度。普通表格、`.fields` 和静态输出保留原有布局。解决
  [#53](https://github.com/pgsty/oink/issues/53)。
- **FileTree**：`wrap=true` 在注释列内完整显示长注释，默认仍保持紧凑。
  解决 [#51](https://github.com/pgsty/oink/issues/51)。

紧凑侧栏叶子节点问题 [#45](https://github.com/pgsty/oink/issues/45) 已在 1.3.0
修复，本版本继续包含该修复。

## 选择 FileTree 注释换行 {#filetree-wrap}

````markdown
```filetree {wrap=true}
- storage/
  - metadata/ # 元数据定义：属性键、顶点标签、边标签、索引和计数器。
  - graph/    # 图数据：顶点、边、索引表，以及 OLAP 分析任务使用的数据。
```
````

省略 `wrap` 或设置 `wrap=false` 时，桌面和平板保留紧凑布局。设置 `wrap=true`
后，注释换行，行高随内容增长，文件名仍使用省略号。目录折叠、分隔条调整、移动端
堆叠和打印展开保持原有行为。详见 [FileTree 使用指南](/zh/docs/components/filetree/#wrap)。

## 构建要求 {#build-requirements}

安装 **Hugo Extended 0.168.0 或更新版本** 和 **独立 Dart Sass 1.105.2**，将其 `sass`
可执行文件放入 `PATH`。普通站点构建仍不需要 Node.js 或 npm。Hugo 0.168
已弃用 LibSass，主样式和 ReDoc 样式改用 Dart Sass 编译。

项目变量覆盖入口和独立 Font Awesome 样式表继续可用。仅屏蔽四类已知的
Bootstrap / import 作用域语言弃用提示，其余告警仍会使 `--panicOnWarning`
发布检查失败。

## 升级 {#upgrade}

安装编译器后执行：

```sh
hugo mod get github.com/pgsty/oink@v1.3.1
env -u HUGO_MODULE_REPLACEMENTS GOWORK=off HUGO_MODULE_WORKSPACE=off hugo --minify --environment production --printPathWarnings --panicOnWarning
```

使用 vendor 或传统主题目录的站点，还需刷新实际主题文件。保留 `preset: paper`
和 `preset_menu: [paper, slate, ink, terminal]`。升级后检查图表、页脚避让、
技术表格，以及显式启用换行的文件树。

## 致谢贡献者 {#thanks}

感谢 [@imbajin](https://github.com/imbajin) 发现这些阅读问题，并提交修复、
测试夹具、回归用例和配套文档：

| 贡献 | Pull request |
| --- | --- |
| Markmap 在不同外观下的文字颜色 | [#48](https://github.com/pgsty/oink/pull/48) |
| 固定 TOC 的页脚避让 | [#50](https://github.com/pgsty/oink/pull/50) |
| 完整 FileTree 注释，最终通过 `wrap=true` 显式开启 | [#52](https://github.com/pgsty/oink/pull/52) |
| 技术表格可读宽度，最终作为显式选项接入 | [#54](https://github.com/pgsty/oink/pull/54) |
| 双语设计契约和配套回归覆盖 | [文档 #11](https://github.com/pgsty/oink.pgsty.com/pull/11) |

合并保留贡献者的原始提交，并补齐默认关闭的 FileTree 参数、正文尺寸变化监听和
浏览器验收覆盖。

---

反链：

- [文档](/zh/docs/)
- [版本升级](/zh/docs/admin/upgrade/)