设计契约 on OINK

Goldmark 块属性实测

Mon, 01 Jan 0001 00:00:00 +0000

已验证快照

这些探针在 Hugo Extended 0.160.1 与 0.164.0 上得到字节一致的相关输出。它们解释 OINK 的原生组件形态；当前组件契约仍是权威。

方法

探针使用一个不带 OINK 模板的最小 Hugo 站点。渲染钩子把上下文字段与 .Attributes 输出为可见标记。站点开启 Goldmark 块属性、行内与块级数学 passthrough 分隔符，以及为检查原始 HTML 而刻意启用的 unsafe 渲染，并设置 wrapStandAloneImageWithinParagraph: false。

架构契约

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 契约

这是随 OINK 0.8.0 正式发布的架构契约。本页是权威中文源文件，与英文版本一同维护在 content/docs/design/。

仓库与装配

仓库根目录是一个完整的 Hugo 模块与主题，不是站点，也不是 npm workspace。 Hugo Extended 负责编译 SCSS 与模板。浏览器运行时与第三方资源都已提交到仓库，因此普通构建不会访问网络。公开的双语文档、示例与浏览器测试位于同级的 oink.pgsty.com 仓库；主题仓库只在 tests/site/ 中保留范围明确的内部回归夹具，不再维护独立的公开示例面。

警告与安全回退

Mon, 01 Jan 0001 00:00:00 +0000

决策

OINK 不调用 Hugo 的 errorf。作者或站点输入无效时，主题发出警告，并使用文档中明确的安全回退，或者省略无效片段。版本发布与部署构建使用 --panicOnWarning，因此同一条警告在发布门禁中仍会导致硬失败。

反向链接与知识图谱

Mon, 01 Jan 0001 00:00:00 +0000

G1 已实现，G2/G3 仍是草案

2026-08-27 决议 G1 的全部待决问题并接受 G1（静态反向链接）。它已在主题 main 分支实现，随 OINK 0.8.0 发布。局部与全站图谱（G2/G3）保持草案状态，等待 G1 的真实使用证据；它们的名称和配置在被接受之前不是公开 API。

媒体收敛

Mon, 01 Jan 0001 00:00:00 +0000

部分已实现

M1（共享 media-result 契约）与 M2（Landing 资源元数据）已在主题 main 分支实现； M3 已决议为方案 2：图片处理只属于原生 Markdown 图片形态，完整 fig 源形态保持容器语义，其参数表刻意不含 command/options。M4（兼容退役）在完成消费方盘点之前保持开放。以下各节为原始设计记录。

配置模型

Mon, 01 Jan 0001 00:00:00 +0000

决策

OINK 保留 Hugo 原生键与仍有价值的 Docsy 兼容键，把主题呈现和行为放在 params.ui.* 下，并用同名的顶层 front matter 键提供页面覆盖。它不增加 params.oink.* 配置树，也不建立一套遮蔽 Hugo 配置模型的注册表。

消费站与迁移证据

Mon, 01 Jan 0001 00:00:00 +0000

带日期的语料快照

这些计数描述 2026 年 8 月被检查的仓库。它们是设计选择的证据，不是实时产品指标或兼容承诺。

语料

创作语料盘点扫描了十一个 OINK 消费站点的 content/ 树：共 5,325 个 Markdown 文件，其中 5,293 个带 YAML front matter。样本同时包含单语言英文与中文参考站、双语产品站、发布归档、自定义落地页，以及独立的 Book 消费站。

组件契约

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 契约

这是随 OINK 0.8.0 正式发布的组件契约。本页是权威中文源文件，与英文版本一同维护在 content/docs/design/。

教程与完整示例位于面向读者的组件专栏。本页定义这些指南所依赖的 API 与行为。

创作模型

一个区块加属性便能表达组件时，使用普通 Markdown；需要复合正文或 Markdown 无法携带的事实时，使用 shortcode。OINK 没有并行的组件注册表。原生形态要求：

OINK 全面审查（2026-08-26）

Mon, 01 Jan 0001 00:00:00 +0000

审查快照，不是新契约

本文记录 2026-08-26 对 github.com/pgsty/oink 主线与本站集成面的审查证据。它不会改变既有 API，也不表示文中建议已经实现。当前行为仍以 Design 契约、实现与 owning checker 为准。

其中一部分已被 OINK 0.7.1 取代。 F01–F06 这些代码问题已在该版本修复，见 0.7.1 发布说明。下面的发现应当读作促成修复的证据，而不是主题当前的状态。

Agent 批量索引

Mon, 01 Jan 0001 00:00:00 +0000

已实现，随 OINK 0.8.0 发布

2026-08-27 决议全部待决问题后接受本提案。两类输出——按顶层 section 分包的 LLMSFULL 与语言根下的 NAVJSON 导航树——都已在主题 main 分支实现，随 OINK 0.8.0 发布，之后本提案退役；发布后的行为由架构契约承担。OINK 已经支持每页 Markdown、语言内 llms.txt、HTML discovery link 与 Copy Markdown；本页只覆盖新增的两类。

Markdown 优先创作

Mon, 01 Jan 0001 00:00:00 +0000

决策

Goldmark 能保留目标语义时，优先提供原生 Markdown 形态。只有原生形态无法表达真实能力时，才保留 shortcode。新增内容场景时延长既有外壳和数据模型，不另建一套并行渲染系统。

外壳与导航契约

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 契约

这是随 OINK 0.8.0 正式发布的外壳与导航契约。本页是权威中文源文件，与英文版本一同维护在 content/docs/design/。

关注点	权威来源
全局导航	Hugo `menus.main`
Docs / Book 侧栏与翻页	内容树或 `data/docs_nav.json`
根栏目切换器	解析后的顶层内容根
内容发现	各语言的本地搜索索引
页面与命令面板操作	共享操作注册表

任何功能都不能引入另一套菜单或页面树。菜单只允许一层子项交互；更深层级会警告，并平铺到带链接的分组标题下。外部链接使用 target="_blank" rel="noopener noreferrer"；内部链接保持语言与子路径感知。

Book 出版链路

Mon, 01 Jan 0001 00:00:00 +0000

已实现出版工具的提案草案

选择启用的 BookManifest、通用 EPUB/PDF runner 与产物校验都已随版本发布，其规范性描述在架构。没有任何一次构建会自己产出这两种文件。本提案仍然未决、且只在本提案未决的，是消费站迁移。

落地页契约

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 契约

这是随 OINK 0.8.0 正式发布的落地页契约。本页是权威中文源文件，与英文版本一同维护在 content/docs/design/。

共享规则见架构契约与组件契约；迁移行为属于迁移边界。

外壳与数据

任何普通页面都可以声明 layout: landing。它渲染顶部导航栏、全宽画布与页脚，不显示 docs 侧栏或 TOC 导轨。首页继续把 data/home/<lang>.yaml 作为兼容的创作路径，并通过同一个渲染器处理。

生成式配置 Schema

Mon, 01 Jan 0001 00:00:00 +0000

决策

schema/ 下的两份 JSON Schema 由 bin/generate-config-schema.py 从主题的 hugo.yaml 与模板读取点投影生成，手工编辑无法通过 CI。Schema 是既有权威的只读投影，不是第三个配置权威。

背景

主题已有两个配置权威：hugo.yaml 在注释旁声明每个默认值；check-params.py 的读取点扫描知道模板实际消费的每一个键。编辑器对两者一无所知，作者只能凭记忆敲 params.ui.* 和 front matter。

OINK 迁移边界

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 契约

这是随 OINK 0.8.0 正式发布的迁移契约。本页是权威中文源文件，与英文版本一同维护在 content/docs/design/。

这是源码与配置指南，不是版本发布流水账。本地源码、提交、标签、推送、消费站点固定版本、部署与生产一致仍是彼此独立的状态。面向读者的升级流程见版本升级。

设计决策

Mon, 01 Jan 0001 00:00:00 +0000

已接受的理由

决策记录解释 OINK 为什么在多个兼容方案中选择了当前设计。上方五份契约仍是现行行为的规范描述；实现与归属检查器仍是可执行事实。

OINK 过去把评审、PRD 与执行记录放在本地 plan/ 目录中。这样既不便发现有价值的推理，也容易让已经放弃的设计看起来仍有权威。已经接受的理由现在统一进入这座双语、版本化的文档站，与它所支撑的契约放在一起。

设计与开发

Mon, 01 Jan 0001 00:00:00 +0000

OINK 0.8.0 契约

本专栏公开随 OINK 0.8.0 正式发布的维护者契约，兼容性下限为 Hugo Extended 0.160.1。唯一的中英文契约源文件位于本站仓库的 content/docs/design/。

本专栏是 OINK 可长期维护的设计记录。站内其它专栏按任务讲解如何搭建站点；这里集中说明现行不变量、这些选择背后的理由、用于比较方案的证据，以及仍处于候选阶段的工作。

设计研究

Mon, 01 Jan 0001 00:00:00 +0000

证据，不是契约

研究记录测量了什么、使用了哪些输入与工具版本。它可以解释决策，但不能覆盖当前契约或实现。

只有其他维护者能够检查方法、理解边界并复现相关检查时，研究才适合进入公开 Design 内容树。原始 Agent 对话、临时构建日志和本机绝对路径不符合这一标准。

设计提案与 PRD

Mon, 01 Jan 0001 00:00:00 +0000

非规范性材料

提案描述的行为可能尚不存在。当前行为由契约、已接受决策、实现与归属检查器定义。不能把提案当作配置参考。

本栏目是 OINK 产品需求文档、RFC 风格设计与未决维护者提案的唯一正本位置。不要在主题仓库或文档仓库中另建本地 plan/、plans/、proposal/ 或其它并行设计树。

设计契约 on OINK

Goldmark 块属性实测

方法

架构契约

仓库与装配

警告与安全回退

反向链接与知识图谱

媒体收敛

配置模型

消费站与迁移证据

语料

组件契约

创作模型

OINK 全面审查（2026-08-26）

Agent 批量索引

Markdown 优先创作

外壳与导航契约

权威来源与导航

Book 出版链路

落地页契约

外壳与数据

生成式配置 Schema

背景

OINK 迁移边界

设计决策

设计与开发

设计研究

设计提案与 PRD