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

2026-08-29 OINK 发布于发布 2243 字 5 分钟

Release

Oink
Release

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

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 即失败的严格构建，再像任何主题升级一样检查真实渲染即可。

概览

当前创作、外壳、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 稳定了什么

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

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

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

0.8.0 之后的全部修改

完整源码比较见 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 身份

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

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

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

正式支持的第一公里

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

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

工具链与兼容性

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 解析模块。

升级

hugo mod get github.com/pgsty/[email protected]
hugo mod tidy
hugo --cleanDestinationDir --gc --minify --environment production \
  --printPathWarnings --panicOnWarning

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

仓库级完整流水账继续记录在 CHANGELOG.md。

加载评论需要启用 JavaScript。在 GitHub 上查看讨论。