设计契约 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.6.0 契约

这是随 OINK 0.6.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

PRD 草案，尚未实现

OINK 当前没有 backlink 区块、局部图谱、全站图谱页或 graph 输出格式。提案中的名称和配置在提案被接受、契约发生变化之前都不是公开 API。

前提

反向导航与页面连接视图是链接图的属性，不是 [[wikilink]] 拼写的属性。Hugo 已经接受普通 Markdown 链接和 ref / relref。OINK 可以从作者已经在写的内容中派生图谱，无需增加解析器、 Goldmark 扩展或并行创作语法。

媒体收敛

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

PRD 草案，只记录剩余工作

OINK 已经具备共享正文图片 resolver、单一 Zoom marker、可处理的 Markdown 图片、编号 figure 与安全的 Landing URL 处理。本页只提议尚未解决的收敛问题，不能把它读成“当前缺失功能清单”。

配置模型

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.6.0 契约

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

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

创作模型

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

Agent 批量索引

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

PRD 草案，部分前提已经存在

OINK 已经支持每页 Markdown、语言内 llms.txt、HTML discovery link 与 Copy Markdown。当前不发布 llms-full.txt 或导航 JSON。本页只提议这两类剩余输出。

Markdown 优先创作

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

决策

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

外壳与导航契约

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

OINK 0.6.0 契约

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

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

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

落地页契约

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

OINK 0.6.0 契约

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

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

外壳与数据

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

OINK 迁移边界

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

OINK 0.6.0 契约

这是随 OINK 0.6.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.6.0 契约

本专栏公开随 OINK 0.6.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 块属性实测

方法

架构契约

仓库与装配

警告与安全回退

反向链接与知识图谱

前提

媒体收敛

配置模型

消费站与迁移证据

语料

组件契约

创作模型

Agent 批量索引

Markdown 优先创作

外壳与导航契约

权威来源与导航

落地页契约

外壳与数据

OINK 迁移边界

设计决策

设计与开发

设计研究

设计提案与 PRD