# OINK 1.2.0：四套风格，本地优先

> OINK 1.2.0 带来 Paper、Slate、Ink、Terminal 四套风格，独立的风格与明暗切换、 本地字体、更清晰的搜索、一致的导航，以及更安全的书籍出版和站点维护工具。

---

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

---

OINK 1.2.0 为同一份技术内容带来四套视觉风格： **Paper**、 **Slate**、 **Ink**
和 **Terminal**。Paper 成为默认外观，Slate 保留熟悉的 OINK 风格。读者可以
分别选择风格与明暗模式，字体和核心脚本仍从站点本地加载。

这次更新也改善了日常阅读与发布体验：中文搜索摘要更清晰，导航与元数据保持
一致，键盘和复制操作更可靠，PDF 导出与维护工具增加了保护。既有站点无需
批量迁移内容。

## 主要变化 {#at-a-glance}

- 同一份内容支持四套风格；Paper 成为默认，既有站点可选择 Slate 保留原貌。
- 一个外观菜单独立管理风格与明暗，支持键盘操作并保存读者偏好。
- 字体、图标与核心运行时本地提供，没有新增字体服务或 CDN 脚本依赖。
- 搜索摘要更有用，页面导航更一致，SEO 正确区分真实译文与语言回退。
- 脚本失败时内容仍可阅读，修复复制、弹窗、数学、图片和图表中的体验问题。
- 书籍出版、快照、迁移与消费站升级工具具有更明确的保护措施。

## 四套风格与外观切换 {#visual-presets}

每套风格调整字体、配色和组件表现，保留相同的内容与导航结构。四套风格均有
浅色和深色配色。

| 风格与视觉特征 | 字体与排版 |
| --- | --- |
| **Paper**：暖色纸面、标题细线、外框表格与柔和阴影 | IBM Plex Sans；适合长文阅读的新默认风格 |
| **Slate**：原有冷色技术配色、圆角表面，以及 Landing 网格与光晕 | Inter 正文与 Chakra Petch 展示标题 |
| **Ink**：黑白底色、红色强调、粗标题线、带下划线的正文链接与方形卡片 | 加粗的 Inter 标题与清晰的无衬线正文 |
| **Terminal**：青绿链接、琥珀强调、紧凑导航与克制的终端细节 | 标题和控件使用等宽字体，正文和表格保持无衬线字体 |

Paper、Slate 是标准选项；Ink、Terminal 可通过显式配置启用，设计仍在完善。
升级时如需保留原有外观，设置 `params.ui.preset: slate` 即可。

点击太阳或月亮按钮打开 **外观** 菜单。 **风格** 用两列图标与名称按钮展示
四个选项； **明暗** 提供亮色、暗色和跟随系统。太阳表示页面当前处于亮色，
月亮表示当前处于暗色。手机上菜单以底部面板展开，键盘选择、Escape 关闭和
焦点返回使用同一套控件。

风格与明暗分别保存。切换风格时尽量保持当前阅读段落的位置，翻页或刷新后恢复
此前选择。选中站点默认风格会清除个人风格覆盖，之后便可跟随站点默认值的变化。

读者风格菜单默认关闭。要提供本站使用的四套风格，可配置：

```yaml
params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true
```

`preset_menu: true` 提供 Paper、Slate 和站点默认预设。字体与强调色覆盖方法见
[外观指南](/zh/docs/customize/brand/#visual-presets)。

新增 IBM Plex Sans 字体与已有字体、图标、样式表、核心浏览器运行时一起随主题
分发。中文使用系统字体回退，显式字体角色覆盖与 `typography: system` 仍优先。
可选 Giscus 评论和站点配置的统计服务保留外部连接，预设切换没有新增外部依赖。
Mermaid、ECharts 仍使用共用的浅深色配色。

## 导航、元数据与图片 {#navigation-and-metadata}

侧栏、上一页/下一页与导航 JSON 对隐藏子树和手动链接使用一致的规则。显式
提供空导航列表时，主题会告警并回退到内容树，保留可用的导航路径。

博客的每一分页拥有独立 canonical URL。SEO 语言备用链接只列出真实译文；
语言选择器回退到目标语言首页时，不再把首页标记为当前文章的译文。从第 2 页
起，归档页省略语言备用链接，因为不同语言的分页边界可能不同。

特色图片依次优先使用页面显式值、页面包图片和继承值。显式选择即使与 cascade
相同，仍保持优先。非法资源 alt 元数据会告警，并保留作者编写的图片描述。

## 阅读与交互 {#rendering-and-interactions}

- **搜索**：只命中 `search_keywords` 的 CJK 查询显示页面描述或摘要，不再展示同义词串；正文命中仍保留上下文。
- **大纲**：合法编码片段和字面百分号都能一致地定位标题，包括靠近页尾的标题。
- **渐进增强**：禁用 JavaScript 或脚本加载失败时，Landing 内容仍可见；指标动画保留作者写出的前缀、后缀与缩写值。
- **键盘与复制**：剪贴板回退恢复选区和焦点，不抢走其他控件的焦点；命令面板失焦后仍能恢复导航，页面快捷键让位于已打开的弹窗。
- **数学与图表**：构建时数学渲染适配 Hugo 0.160.1 与本地 KaTeX CSS，编号公式在窄屏换行，Mermaid 暗色标签提高对比度；非法 PlantUML/Draw.io 端点在加载运行时前告警，Draw.io 编辑与图片缩放保持独立。

## 仓库操作 {#repository-actions}

编辑、历史与新建子页链接更一致地处理 Windows 源文件路径和外部内容挂载。
外部挂载仍需显式 `path_base_for_github_subdir` 映射；映射后的路径如果仍为
绝对路径、带盘符或逃出仓库边界，就省略这些源码操作，避免暴露构建机器路径或
链接到错误文件。详见[仓库链接](/zh/docs/customize/repository/#imported-content)。

## 文档与兼容性 {#compatibility}

中英文指南已覆盖新风格及修正后的阅读、导航与出版行为。Hugo Extended 兼容
下限仍为 **0.160.1**，CI 使用 **0.165.0**，模块声明 Go **1.27.0**。
在 Hugo 0.160.x 上，非默认通用 `zh` 与区域中文语言包并存时，仍需
`locale: zh-CN`。

既有站点先决定采用 Paper 还是保留 Slate，再核对复制到站点内的导航、图片、
数学和运行时覆盖。无需重写内容，配置与验证步骤见
[1.2 升级清单](/zh/docs/admin/upgrade/#preparing-1-2)。

可选的 [OINK CLI](/zh/docs/cli/) 是独立项目，拥有自己的发布周期，普通 Hugo
构建不依赖它。

## 维护与出版工具 {#maintenance-and-publication}

Book PDF 导出同时限制直接和间接资源请求。默认只允许本地出版 origin 与
数据 URL 中的媒体；禁用脚本，拒绝刷新导航，符号链接不能逃出构建树。
`--allow-remote-resources` 允许被动 HTTP(S) 媒体，不开放脚本或本地文件访问。
替换已有输出仍需 `--force`。

快照工具拒绝与站点源码、主题源码、运行工具的 checkout 或其他快照重叠的目标，
包括符号链接别名和保留输出。迁移工具保留列表与引用块中嵌套的围栏示例，包括
示例中字面的引用与围栏标记。

## 消费站升级流程 {#consumer-upgrades}

新增 `bin/update-consumers.py`，帮助维护者升级一组站点。工具默认只读清点；
`--write` 更新模块文件，`--check` 核对精确模块版本，并在禁用继承的模块替换和
workspace 后执行将警告视为失败的构建。

链接 worktree、隐藏副本与非默认分支会跳过并留待核对。Vendor 刷新必须显式
开启，其他工作会保留，单个站点失败不影响其余站点。工具不提交、推送或部署，
详见[消费站维护契约](/zh/docs/design/migration/#updating-consumers)。

## 验证与安装 {#verification}

10 月 5 日的候选版本已通过主题检查器、运行时测试、文档站非浏览器与浏览器
套件、选定的 Hugo 下限兼容检查，以及根路径和子路径 EPUB/PDF 检查。
[发布前审查](/zh/docs/design/research/2026-10-05-v1-2-release-review/)
记录了准确范围、工具版本与已知边界。

OINK 1.2.0 已在 [GitHub Releases](https://github.com/pgsty/oink/releases/tag/v1.2.0)
发布。升级主题后，提交更新的模块文件：

```bash
hugo mod get github.com/pgsty/oink@v1.2.0
hugo mod tidy
```

---

反链：

- [文档](/zh/docs/)