# OINK 1.0.0：稳定契约、Starter 与正式发布

> OINK 1.0.0 将现有知识发布契约定为稳定表面，并汇总 0.8.0 之后的全部主题修改： Print 与 Book 正确性、固定的 Go 1.27 与 Hugo 0.165.0 发布工具链、正式支持的 Starter，以及进入更广泛 Hugo 生态所需的公开元数据与展示素材。

---

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

---

OINK 1.0.0 是稳定性里程碑，不是临发布前重置 API。它把整个 0.x 周期形成的组件、
配置、内容、输出与维护者契约提升为第一个主版本。本说明汇总 `v0.8.0..v1.0.0`
范围内的全部主题修改；0.8.0 已经交付的 Agent 输出与反向链接是比较基线，不会再
冒充 1.0 新功能重复计算。

已经使用 0.8.0、0.8.1 或 0.8.2 的站点不需要迁移内容或配置。把模块固定到新版本，
执行 warning 即失败的严格构建，再像任何主题升级一样检查真实渲染即可。

**v1\.0\.0 · 2026-08-29**
- [查看发布](https://github.com/pgsty/oink/releases/tag/v1.0.0)
- [源码 · tar\.gz](https://github.com/pgsty/oink/archive/refs/tags/v1.0.0.tar.gz)
- [源码 · zip](https://github.com/pgsty/oink/archive/refs/tags/v1.0.0.zip)
- [pgsty\/oink](https://github.com/pgsty/oink)

## 概览 {#at-a-glance}

- 当前创作、外壳、Landing、Book、Release、Print、Markdown 与 Agent 输出契约，
  现在共同构成 OINK 1.0 的稳定表面。
- 单页 Print 保留普通页面的标题与脚注 ID；只有多页分区 Print 与整书 Print 才为
  页面局部目标增加命名空间。
- 长标题换行时，Book 侧栏编号仍保持为不可压缩、不可拆分的原子单元。
- 主题 CI、文档站与 OINK Starter 使用 Go 1.27 和 Hugo Extended 0.165.0；公开
  声明的 Hugo 兼容下限仍为 Extended 0.160.1。
- OINK Starter 成为进入框架的正式起点，提供中性的 Docs、Blog、Book 内容，以及
  严格的 GitHub Pages 与 Cloudflare Pages workflow。
- README、主题元数据、案例链接、徽章与优化后的 3:2 Hugo Themes 展示图，现在
  描述和呈现的是代码真正交付的同一个产品。

## 1.0 稳定了什么 {#stable-contracts}

主版本号约束的是契约，不是宣称界面从此停止演进。OINK 仍可在 1.x 增加组件与可选
输出；1.0 的含义是普通站点不必在每个次版本重新学习或改写当前基础。

| 表面 | 1.0 契约 |
| --- | --- |
| 内容 | 原生 Markdown 仍是源文件；组件对非交互输出保持明确的静态降级 |
| 配置 | `params.ui.*` 管理主题策略，页面覆盖去掉该前缀，非法作者输入告警并使用安全回退 |
| 外壳 | Docs、Blog、Book、Swagger/Redoc 与 Landing 各自保留清晰、成文的职责 |
| 输出 | HTML、RSS、Print、Markdown、LLMS、LLMSFULL、NAVJSON 与 BookManifest 保持明确的选择启用与降级边界 |
| 运行时 | 第三方资源继续本地化，能力代码只在实际渲染内容需要时加载 |
| 维护 | 实现、归属检查器、双语契约、发布状态、消费站固定版本与部署继续作为独立证据 |

规范性的中英文记录位于[设计与开发](/zh/docs/design/)；其状态现在统一为
`released-v1.0.0`。带日期的研究与活跃提案仍是证据或未来工作，不会暗中算作
已经交付的 1.0 能力。

## 0.8.0 之后的全部修改 {#changes-since-080}

完整源码比较见
[`v0.8.0...v1.0.0`](https://github.com/pgsty/oink/compare/v0.8.0...v1.0.0)。
其中是一组刻意收敛的稳定化改动：

| 范围 | 修改 | 用户可见结果 |
| --- | --- | --- |
| Book 侧栏 | 固定编号单元，并为编译后 CSS 增加回归断言 | 长标题换行时不会再压缩、裁切或拆开章节编号 |
| Print 锚点 | 区分单页 Print 与分区 / 整书聚合，再刷新输出 golden | 普通页面有效的 fragment 在该页 Print 中继续有效；聚合文档的 ID 仍不会冲突 |
| 主题 CI | 用一个固定的 Extended 0.165.0 工具链替代历史 Hugo 矩阵，并为模块模式明确固定 Go 1.27 | 发布证据与当前上游工具链一致，0.160.1 Hugo 下限则继续单独成文 |
| 公开 README | 围绕 OINK Starter 重写第一条上手路径，补齐能力、兼容性、生产案例、文档入口与 Docsy 边界 | 访客无需反向拆解回归站就能评估项目 |
| Hugo Themes 素材 | 换成优化过的 3:2 Landing 截图 | 图库得到不带浏览器边框、大小分别为 166,526 与 68,488 字节的 PNG |
| 主题元数据 | 扩展描述、标签与特性，统一 OINK 字标，记录 Docsy 原始主题身份 | 目录中的归属与可发现性符合仓库真实范围 |
| 模块 directive | 0.8.2 临时适配旧版 Go 1.26 上游构建器；1.0 随更新后的上游流程回到 Go 1.27 | 只改变模块准入；OINK 仍无 Go 源码，directive 不改变渲染结果 |

这个范围没有组件改名、配置键移除、默认值翻转或内容语法迁移。

## 正确的 Print 身份 {#print-identities}

页面局部 ID 与聚合文档 ID 解决的是两类问题。普通页面与它自己的 Print 表示是同一
份文档的两种视图，因此作者明确编写或 Goldmark 生成的标题、脚注 ID 应保持一致。
分区 Print 与整书 Print 会组合多个源页面，两个章节可能都带 `#overview` 或 `fn:1`，
所以这些目标必须增加源页面命名空间。

| 输出 | 标题与脚注 ID |
| --- | --- |
| 普通 HTML 页面 | 作者明确编写或 Goldmark 生成的页面局部 ID |
| 单页 Print | 与普通 HTML 相同的页面局部 ID |
| 多页分区 Print | 增加源页面命名空间 |
| 整书 Print | 增加源页面命名空间 |

Book 图、表、公式、示例，以及改写后的跨页链接继续沿用现有显式目标规则。修复只是把
命名空间限制到真正聚合多份文档的两种输出。

## 正式支持的第一公里 {#supported-starter}

OINK Starter 现在属于正式支持的发布表面，而不是非正式演示。它从小而中性的项目站
开始：三种语言 profile、Docs、Blog、Book、本地资源与两条 warning 即失败的部署
workflow。它刻意排除了 OINK 自身的分析账号、评论、品牌、文档全集、浏览器套件与
维护者 fixture。

[Starter 教程](/zh/docs/start/starter/)按由浅入深的顺序推进：先建立未修改基线，
再设置身份、选择语言、替换首页数据、改写内容与导航、增加品牌、启用完整集成、执行
严格构建，最后才部署。已有 Hugo 站点仍可以采用更小的
[从零接入模块路径](/zh/docs/start/from-scratch/)。

## 工具链与兼容性 {#compatibility}

Hugo 官方主题更新流程在本次发布当天升级到 Go 1.27 与 Hugo 0.165.0。OINK 1.0
跟随这条当前发布基线：

| 依赖 | OINK 1.0 策略 |
| --- | --- |
| Hugo | Extended 0.160.1 或更新版本；发布、站点与浏览器验证固定 0.165.0 |
| Go | 解析 Hugo Module 时需要 1.27 或更新版本 |
| Node.js | 消费站构建与运行均不需要 |

短暂存在的 0.8.2 只降低了模块的 `go` directive，让当时固定 Go 1.26、使用本地
工具链选择的官方更新器可以准入主题。上游转到 1.27 后，继续保留这一例外已无法描述
真实发布环境。OINK 本身仍由模板、样式、资产与检查器组成，不包含 Go 源码。使用离线
归档或 Git submodule 时不需要 Go 解析模块。

## 升级 {#upgrade}

```bash
hugo mod get github.com/pgsty/oink@v1.0.0
hugo mod tidy
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings --panicOnWarning
```

提交 `go.mod` 与 `go.sum`，再检查有代表性的 Docs、Blog、Book、Print、语言、深浅色
与窄屏路由。本地构建成功、公开标签、可解析的模块校验和、消费站固定版本、部署与线上
渲染仍是彼此独立的发布状态。

仓库级完整流水账继续记录在
[CHANGELOG.md](https://github.com/pgsty/oink/blob/main/CHANGELOG.md)。