跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

设计决策

解释 OINK 现行公开契约与实现为何采用当前形态的已接受选择。
已接受的理由

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

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

决策地图

决策 解决的问题
警告与安全回退 为什么普通预览能容忍错误输入，而发布仍保持严格
配置模型 配置放在哪里、页面如何覆盖，以及 OINK 为什么不另造配置命名空间
Markdown 优先创作 为什么优先使用原生 Markdown，以及 Docs、Blog、Book、Landing 如何延长共享系统

记录格式

一份已接受决策应记录背景、选择、后果，以及证明该选择仍然成立的证据。它不重复参数 参考或教程。每份决策都要链接到归属契约与验证面，中英文页面必须同步修改。

决策发生变化时，应在同一次交付中更新实现、检查器、受影响契约与决策记录。旧答案留在 Git 历史和版本变更记录中，不在导航树里并列保留两套“现行”答案。

相关

1 - 警告与安全回退

作者输入无效时，预览阶段发出警告并安全降级；–panicOnWarning 在发布阶段恢复硬门禁。
决策

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

背景

Hugo 把整座站点作为一次事务构建。编辑一页时触发的 errorf 会让该次重建中的所有 URL 都返回错误，包括无关页面和首页。服务器进程仍然存在，修正输入后也会自动恢复，但多人共享 的预览在此期间完全不可用。

警告的开发成本不同。出错的值可以回退，站点其余部分仍可检查，作者也能看到准确消息。 发布构建则不会放过它，因为 OINK 的 CI 与集成门禁都会加上 --panicOnWarning。

决策

校验遵循四条规则：

  1. 点明无效键和值、允许的形状以及实际采用的回退值。
  2. 值来自页面 front matter 时带上页面位置；站点级错误不要在每一页重复刷屏。
  3. 不允许无效值继续参与后续运算。先校验，再用规范化后的值渲染。
  4. 没有诚实回退时，警告并且不渲染。不能为了继续构建而编造内容、发起网络请求或输出 不安全 URL。

枚举、布尔、CSS 长度与数字的共享校验形状位于 layouts/_partials/validate.html。领域 resolver 可以增加更窄的规则，但必须保留同一套 警告与回退契约。

安全边界

继续构建不等于继续输出危险内容。被拒绝的 CSS 长度要在进入 style 属性之前回退；远程服务 配置不完整时，要在浏览器可能发起请求之前省略组件；不安全的操作 URL 直接丢弃。真正的保护是 坏输出没有出现，而不是 Hugo 被终止。

这也把编辑与发布清晰分开：

阶段 无效输入的处理
hugo server 或普通本地构建 警告、回退或省略，其它页面继续可用
CI、版本验收、部署 同一警告在 --panicOnWarning 下让构建以非零状态退出

后果

  • 每个回退值都是公开契约的一部分，必须与主题声明的默认值一致。
  • 从“失败”改成“回退”时，测试也必须改变。负向测试要同时证明普通构建存活、警告文案、 渲染后的回退，以及严格构建失败。
  • 检查器必须直接验证被拒绝的输出。例如 URL 安全测试应断言危险 URL 没有进入产物，不能把 任意构建失败当作充分证据。
  • 参数源码检查器守住主题 layout 中不存在 errorf 调用这一不变量。

验证

本决策的归属参考包括 架构契约、 bin/check-params.py，以及主题夹具与本站的严格构建。

2 - 配置模型

OINK 延长 Hugo 与 Docsy 兼容配置，不另造第二套命名空间或全局 resolver。
决策

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

背景

OINK 继承了成熟的配置面，又增加了阅读外壳、内容输出和本地交互。早期设计曾尝试把所有 主题自有键迁入一个新命名空间，并在每页一次性解析完整配置字典。这样会在 Hugo 原生键旁边 再造一种语言，使 section cascade 更复杂，迁移规模甚至超过它要控制的行为本身。

现行模型直接体现每一层的归属：

层次 职责 示例
Hugo 站点身份、语言、菜单、输出、分类法、markup、模块 baseURL、languages、outputs
站点事实与集成 仓库、版本、作者、本地搜索、评论、外部服务 params.github_repo、params.version、params.comments
OINK 界面 外壳、导航、呈现与本地交互 params.ui.sidebar_*、params.ui.typography、params.ui.share
页面或栏目 对可覆盖站点默认值的局部调整 sidebar_enabled、featured_image、share
数据文件 不是开关的结构化事实与有序内容 data/landing、data/download、data/docs_nav.json

决策

配置 API 遵循以下规则：

  1. 站点事实保留在既有顶层；界面选择归入 params.ui.*。
  2. 页面覆盖去掉 ui. 前缀，其余名称保持一致。section 的 cascade 可以把这个顶层键应用到后代。
  3. 一个布尔值足以表达完整政策时使用标量；只有真正存在下级设置时才使用 map。既有 map 可以接受 布尔速记。
  4. 名称采用正向、snake_case，并按功能分组。密切相关的设置共用前缀，不为此再建一层 resolver。
  5. 主题默认值声明在主题的 hugo.yaml 中。只有静态值会抹掉刻意存在的外壳差异时，模板才可以 推导默认值。
  6. 每个功能族负责自己的规范化与校验。共享 helper 提供常见形状，但不存在一套悄悄重写任意旧键的 全局兼容注册表。

完整的现行键、类型与默认值统一放在配置参考中。本决策只记录 归属规则，不再维护第二张参数表。

兼容策略

公开键改名时，由归属 resolver 给出定向警告，同时提供迁移说明和负向测试。已移除或拼错的键 不构成永久别名层的理由。Hugo 与第三方原生 camelCase 键继续保留原样；OINK 自有新增使用 snake_case。

页面值通过 Hugo 普通的 front matter 与 cascade 模型解析。OINK 不要求作者在 front matter 里写嵌套 ui: 树，也不承诺合并任意嵌套页面 map。

后果

  • 新增公开设置时，必须有声明或明确推导的默认值、归属 resolver、文档，以及正向和负向测试。
  • 配置指南链接到唯一参考表，不在各处重复类型与默认值。
  • 只有有序或重复事实才值得新增数据结构，不能只因为不想增加参数就造一个 data 文件。
  • 无效标量值遵循警告与回退决策。

验证

bin/check-params.py 审计声明默认值、页面别名、警告行为与禁止 errorf 的不变量。公开参考及其 中文对页由集成站的双语和渲染链接检查覆盖。

3 - Markdown 优先创作

原生 Markdown 承载常见语义；shortcode 只填补真实能力缺口，各内容模型延长共享外壳而不是分叉。
决策

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

背景

OINK 同时服务短手册、大型参考文档、发布归档、落地页和书籍。对十一个消费站点、五千多篇 Markdown 的盘点呈现了两个极端：有些页面几乎不用主题语法，有些页面则由大量嵌套 shortcode 与站点自有 layout 拼成。

只为后一类优化的组件 API 会变成私有 DSL；只支持纯 Markdown 又会迫使书籍、富图、标签页和 结构化发布退回站点自有 HTML。真正有用的边界是能力，而不是语法看起来是否新颖。

决策

OINK 按以下顺序设计：

  1. 原生 Markdown 优先。 列表可以成为 Steps、Cards 或 FileTree 标记；表格可以成为 Fields 或矩阵；blockquote 可以成为 callout；代码围栏、图片与 passthrough 块通过渲染钩子携带属性。
  2. shortcode 只补能力。 CommonMark 缩进、嵌套容器、处理选项或跨页登记无法安全表达同一结果时， 才保留全量 shortcode 形态。
  3. 语义实现只有一套。 原生形态与全量形态进入同一组规范化 partial 和输出契约，不能只是两种 外观相似的组件。
  4. 沿一条系统延长。 新 Landing 区块进入 section 注册表；新 Blog 呈现仍是 Blog 变体；Book 编号接入内容原语与导航系统。OINK 不为一个功能再造第二套卡片、落地页、导航或 Article 外壳。
  5. 事实不藏在呈现字符串里。 版本、仓库、日期与有序记录来自 front matter、站点参数或数据文件。 shortcode 参数不能成为第二个事实来源。

输出契约

只有在每种已启用输出中都得到明确语义结果，一种创作形态才算完整：

输出 要求
HTML 服务器端先输出完整语义内容，JavaScript 只做增强
Print 静态、展开，不包含依赖交互的控件
Markdown / LLMS 保持源码形态的正文、链接、列表、表格与围栏，不泄漏组件 HTML
RSS 安全的静态内容，或者明确省略

这一要求避免一个漂亮的 HTML-only 组件悄悄破坏 Agent 输出、订阅源或整书打印。

信任与呈现

渲染钩子与 shortcode 使用明确的属性白名单。不安全 URL scheme、内联事件处理器和任意 style 输入会被丢弃。只有在文档明确规定、下游站点 CSS 已属于既有创作契约的表面，才接受作者 class。 图标使用一对 Font Awesome class；OINK 不再发明第二种图标 ID 语言。

后果

  • 提议新组件时，必须先说明 Markdown 加既有渲染钩子为什么不够。
  • 保留全量 shortcode 时，必须点明它独有的能力，并测试两种形态进入相同的规范化输出。
  • 外壳变体使用相互独立的呈现键，因此启用 Hero 或流式大纲不会改变分类法、订阅源、翻页顺序或 内容类型。
  • 消费站证据是带日期的研究，不是永久冻结偶然语法的理由。当前公开面仍由 组件契约与外壳契约定义。

验证

主题的组件、Book、输出与 golden 检查器先验证创作契约，本站的双语示例与浏览器套件再完成集成 验收。原生形态背后的 Goldmark 事实记录在 块属性研究中。