设计决策 on OINK

警告与安全回退

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

决策

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

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

决策

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

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。