这是本节的多页打印视图。 .
设计研究
- 1: Goldmark 块属性实测
- 2: 消费站与迁移证据
研究记录测量了什么、使用了哪些输入与工具版本。它可以解释决策，但不能覆盖当前契约或实现。
只有其他维护者能够检查方法、理解边界并复现相关检查时，研究才适合进入公开 Design 内容树。 原始 Agent 对话、临时构建日志和本机绝对路径不符合这一标准。
研究地图
| 记录 | 证据 |
|---|---|
| Goldmark 块属性 | 支持的 Hugo 下限版本上，渲染钩子能看到什么，以及 CommonMark 容器的边界 |
| 消费站与迁移证据 | 带日期的语料盘点与确定性 Book 迁移结果 |
发布规则
研究记录必须说明日期、输入、相关版本、方法、结果与已知边界。容易变化的数字明确标为快照。 涉及外部框架的比较，公开前要依据一手资料重新核验，并提炼成与 OINK 有关的结论，不能直接 复制成竞品目录。
1 - Goldmark 块属性实测
这些探针在 Hugo Extended 0.160.1 与 0.164.0 上得到字节一致的相关输出。它们解释 OINK 的原生组件形态；当前组件契约仍是权威。
方法
探针使用一个不带 OINK 模板的最小 Hugo 站点。渲染钩子把上下文字段与 .Attributes 输出为
可见标记。站点开启 Goldmark 块属性、行内与块级数学 passthrough 分隔符，以及为检查原始 HTML
而刻意启用的 unsafe 渲染，并设置 wrapStandAloneImageWithinParagraph: false。
每种源码形态分别用兼容下限版本和当时的当前 Hugo 版本渲染，再逐字节比较相关产物。以下结论 记录平台行为，不涉及视觉样式。
结论
| 源码形态 | 钩子结果 | 设计意义 |
|---|---|---|
含段落、围栏、callout、嵌套列表并以 {.steps} 结尾的有序列表 |
class 落在最外层 <ol>，列表项中的富块内容完整保留 |
Markdown 列表可以成为 Steps 原生形态 |
| 列表项内标题 | 标题保留在 <li> 内，并进入 .TableOfContents |
原生 Steps 可以携带可导航标题 |
以 {.filetree} 结尾的嵌套列表 |
class 落在最外层 <ul> |
FileTree 不需要只为保持层级再包 wrapper |
独占图片加 {#id num= caption= .class} |
render-image 收到 IsBlock=true 和全部属性 |
Book 图可以有原生图片形态 |
| 段落中的行内图片 | IsBlock=false，图片收不到块属性 |
行内图片不能使用块级 figure 契约 |
块级公式加 {#id num=} |
render-passthrough 收到 block 类型与属性 |
编号公式可以使用原生 passthrough 形态 |
表格加 {.fields #id num= caption=} |
render-table 收到 class 与命名属性 |
Fields、矩阵、题注和 Book 编号可以共享一个钩子 |
代码围栏加 {#id num= caption=} |
code-block 钩子收到属性 | 围栏本身可以成为编号示例 |
callout 加 {icon= tab=} |
blockquote 钩子同时收到 callout 元数据与属性 | 折叠、标题行内标记、图标和 tab 元数据可以共存 |
| 属性行与目标块之间隔一个空行 | 属性会静默消失 | 源码检查必须拒绝孤立属性行 |
两张相邻表分别带 tab= |
每个 table 钩子收到自己的 tab 标签 | 相邻块 tab 机制可以扩展到代码围栏之外 |
容器边界
Hugo 的 % shortcode delimiter 会把 .Inner 渲染成 Markdown，但模板必须在内部 Markdown
前后各输出一个空行。缺少任一空行时，后续列表可能被当作 HTML block 的字面内容，而不是 Markdown。
把多行 % 容器放进 CommonMark 列表项还有更硬的限制：生成的 HTML 不会随列表内容缩进，列表会在
容器之前闭合，并在容器之后重新开始。因此，当步骤中必须放另一个全量容器时，OINK 仍保留全量
Steps 形态。普通富块、围栏与 < shortcode 不受这一限制。
在相关收集器形态中，嵌套 % shortcode 收到的也是已经渲染好的内部 HTML。需要保留子项原始
Markdown 的收集器应使用 < delimiter，再通过共享的作用域块渲染器处理捕获到的正文。
属性归属
钩子能看到某个属性，并不等于它自动成为公开属性。每个钩子拥有文档明确的白名单。style 与内联
on* 处理器会被拒绝；携带 URL 的值必须经过共享 URL 策略。只有下游 CSS 已属于既有扩展机制的
表面，才保留站点 class。
实验还表明：gallery 列表项中的图片可以被视为块图，却仍不知道父列表带有什么 marker。因此运行时 要么依赖主题显式输出的标记，要么保留一条窄的结构兜底，不能假设图片钩子能看到任意祖先。
边界与验证
这些结果只覆盖 Hugo 0.160.1、0.164.0 与上述 Goldmark 设置。修改设置的站点或未来 Hugo 版本不在 承诺范围内。调整 Hugo 兼容下限时，应先重跑组件、Book、表格、gallery 与 Markdown 输出检查，再更新 这份快照。
2 - 消费站与迁移证据
这些计数描述 2026 年 8 月被检查的仓库。它们是设计选择的证据，不是实时产品指标或兼容承诺。
语料
创作语料盘点扫描了十一个 OINK 消费站点的 content/ 树：共 5,325 个 Markdown 文件，其中
5,293 个带 YAML front matter。样本同时包含单语言英文与中文参考站、双语产品站、发布归档、
自定义落地页，以及独立的 Book 消费站。
盘点刻意测量源码 Markdown，而不是生成后的 HTML。统计项包括 shortcode 调用、代码围栏属性、 callout、表格 marker、原始 HTML、front matter 键、内容类型与站点自有 layout。随后针对五个 长篇内容消费者又做了一轮 Book 专项盘点。
改变设计的结论
| 证据 | 形成的选择 |
|---|---|
| 内容从近乎纯 Markdown 到大量嵌套组件同时存在 | 原生 Markdown 是默认形态；只有明确能力缺口才保留全量形态 |
| 文档、Blog、Landing、发布与书籍反复在站点侧重做导航或卡片 | 延长共享外壳、注册表和内容原语，不增加并行系统 |
| 站点自有表格 class 很常见，匹配 canonical Fields 表头的表格却很少 | 钩子属性使用白名单，但保留文档明确的站点 class 扩展点；不能从任意二列表格猜测 Fields |
| Book 站各自拥有图、表、公式、示例和交叉引用约定 | 编号原语与迁移 profile 必须确定性分类、保留稳定 ID，并验证渲染目标 |
| 站点同时存在单语言、对页双语和生成式语言内容 | 必须明确语言权威与生成边界；迁移不能把未跟踪的生成树当作源码 |
| 富 HTML 页面仍要提供 Print、Markdown、订阅源和 Agent 输出 | 接受交互 HTML 之前，每个组件先声明所有输出中的降级行为 |
证据也否决了若干看起来诱人的新增项：文档站不足以支撑第二套 Landing 系统；Book 站不需要新封面 组件；连载归档不值得增加独立 shell type；远程 API 采集属于站点侧 CI，而不是承诺本地构建的 Hugo 主题。
块与表格证据
针对十一个站点与 Book 消费者的专项盘点共发现 11,484 张 pipe table。只有 11 张已经匹配严格的
Fields 表头词汇，约 874 张属于参考型表格，约 1,300 张属于兼容矩阵。因此 OINK 采用显式
.fields 与 .matrix marker，不按表格形状猜测语义。
同一轮盘点在十一个站点中发现 18 个 Steps 块，它们都使用带标题和富内容的全量形态。平台探针表明，
原生有序列表可以承载其中大多数内容，却不能在列表项内安全容纳另一个全量 % 容器。因此 OINK 保留
两种形态是为了技术能力边界，而不只是书写偏好。
确定性 Book 迁移
三个带日期的干跑 profile 用于证明迁移规则能解释每个被识别的来源，而不编造语义：
| Profile 快照 | 分类结果 | 人工边界 |
|---|---|---|
| DDIA v2 | 106 张图、3 张表、22 个代码示例，相关 304 条链接全部入账 | 1 条题注链接降级为可见文本，无未解释跳过项 |
| DDIA v1 | 90 张编号图与 203 条匹配引用 | 14 张装饰性或无编号图片刻意不处理 |
| TPME | 31 张图、10 张表、44 条编号引用与 1,018 条通用稳定引用 | 被识别项目零跳过 |
| 私有 Book profile | 119 张图、5 张表与 136 条编号引用 | 3 张歧义图片保留人工复核 |
每个 profile 都先干跑，只在歧义边界明确后写入；第二次执行变更数为零；随后以警告即失败的模式 构建，并通过渲染后的 kind、编号和锚点检查。公开迁移工具与当前 profile 边界见 创作书籍和 迁移契约。
边界
这些数字不能直接用于产品宣传，也不能当作当前站点清单。重做研究时，需要重新确定仓库清单并生成 新的带日期报告。本公开记录刻意排除了本机路径、未提交内容、私有仓库名称、原始 Agent 对话与生成 构建产物。