分类: 设计契约

非规范性材料 提案描述的行为可能尚不存在。当前行为由契约、已接受决策、实现与归属检查器定义。不能把提案 当作配置参考。 本栏目是 OINK 产品需求文档、RFC 风格设计与未决维护者提案的唯一正本位置。不要在主题仓库或 文档仓库中另建本地 plan/、plans/、proposal/ 或其它并行设计树。 当前提案 提案 当前边界 反向链接与知识图谱 草案；当前没有 graph 或 backlink 实现 媒体收敛 草案；共享正文 resolver 与 Zoom marker 已落地，只记录剩余 …

证据，不是契约 研究记录测量了什么、使用了哪些输入与工具版本。它可以解释决策，但不能覆盖当前契约或实现。 只有其他维护者能够检查方法、理解边界并复现相关检查时，研究才适合进入公开 Design 内容树。 原始 Agent 对话、临时构建日志和本机绝对路径不符合这一标准。 研究地图 记录 证据 Goldmark 块属性 支持的 Hugo 下限版本上，渲染钩子能看到什么，以及 CommonMark 容器的边界 消费站与迁移证据 带日期的语料盘点与确定性 Book 迁移结果 发布规则 研究记录必须说 …

OINK 0.6.0 契约 本专栏公开随 OINK 0.6.0 正式发布的维护者契约，兼容性下限为 Hugo Extended 0.160.1。唯一的中英文契约源文件位于本站仓库的 content/docs/design/。 本专栏是 OINK 可长期维护的设计记录。站内其它专栏按任务讲解如何搭建站点； 这里集中说明现行不变量、这些选择背后的理由、用于比较方案的证据，以及仍处于 候选阶段的工作。 如何阅读本专栏 层次 含义 契约 兼容实现必须保留的规范性行为 决策 用于解释现行行为的已接受理由 …

已接受的理由 决策记录解释 OINK 为什么在多个兼容方案中选择了当前设计。上方五份契约仍是 现行行为的规范描述；实现与归属检查器仍是可执行事实。 OINK 过去把评审、PRD 与执行记录放在本地 plan/ 目录中。这样既不便发现有价值的 推理，也容易让已经放弃的设计看起来仍有权威。已经接受的理由现在统一进入这座双语、 版本化的文档站，与它所支撑的契约放在一起。 决策地图 决策 解决的问题 警告与安全回退 为什么普通预览能容忍错误输入，而发布仍保持严格 配置模型 配置放在哪里、页面如何覆盖， …

OINK 0.6.0 契约 这是随 OINK 0.6.0 正式发布的迁移契约。本页是权威中文源文件，与英文版本 一同维护在 content/docs/design/。 这是源码与配置指南，不是版本发布流水账。本地源码、提交、标签、推送、消费站点 固定版本、部署与生产一致仍是彼此独立的状态。面向读者的升级流程见 版本升级。 工具范围 bin/migrations/oink06.py 只扫描和自动改写站点内容目录下的 Markdown 文件， 包括受支持的 YAML front matter。它不 …

OINK 0.6.0 契约 这是随 OINK 0.6.0 正式发布的落地页契约。本页是权威中文源文件，与英文版本 一同维护在 content/docs/design/。 共享规则见架构契约与 组件契约；迁移行为属于 迁移边界。 外壳与数据 任何普通页面都可以声明 layout: landing。它渲染顶部导航栏、全宽画布与页脚， 不显示 docs 侧栏或 TOC 导轨。首页继续把 data/home/<lang>.yaml 作为兼容的创作 路径，并通过同一个渲染器处理。 非首页依次从内联 …

OINK 0.6.0 契约 这是随 OINK 0.6.0 正式发布的外壳与导航契约。本页是权威中文源文件， 与英文版本一同维护在 content/docs/design/。 权威来源与导航 关注点 权威来源 全局导航 Hugo menus.main Docs / Book 侧栏与翻页 内容树或 data/docs_nav.json 根栏目切换器 解析后的顶层内容根 内容发现 各语言的本地搜索索引 页面与命令面板操作 共享操作注册表 任何功能都不能引入另一套菜单或页面树。菜单只允许一层子项交互； …

决策 Goldmark 能保留目标语义时，优先提供原生 Markdown 形态。只有原生形态无法表达真实能力时， 才保留 shortcode。新增内容场景时延长既有外壳和数据模型，不另建一套并行渲染系统。 背景 OINK 同时服务短手册、大型参考文档、发布归档、落地页和书籍。对十一个消费站点、五千多篇 Markdown 的盘点呈现了两个极端：有些页面几乎不用主题语法，有些页面则由大量嵌套 shortcode 与站点自有 layout 拼成。 只为后一类优化的组件 API 会变成私有 DSL；只 …

PRD 草案，部分前提已经存在 OINK 已经支持每页 Markdown、语言内 llms.txt、HTML discovery link 与 Copy Markdown。 当前不发布 llms-full.txt 或导航 JSON。本页只提议这两类剩余输出。 当前基线 站点可以为 page 与 section 启用 Hugo 的 Markdown 输出，并为 home 启用生成 llms.txt 的 LLMS 输出。OINK 把 shortcode 渲染成语义化 Markdown，保留源码 …

OINK 0.6.0 契约 这是随 OINK 0.6.0 正式发布的组件契约。本页是权威中文源文件，与英文版本 一同维护在 content/docs/design/。 教程与完整示例位于面向读者的组件专栏。本页定义这些 指南所依赖的 API 与行为。 创作模型 一个区块加属性便能表达组件时，使用普通 Markdown；需要复合正文或 Markdown 无法携带的事实时，使用 shortcode。OINK 没有并行的组件注册表。原生形态要求： markup: goldmark: …

带日期的语料快照 这些计数描述 2026 年 8 月被检查的仓库。它们是设计选择的证据，不是实时产品指标或兼容承诺。 语料 创作语料盘点扫描了十一个 OINK 消费站点的 content/ 树：共 5,325 个 Markdown 文件，其中 5,293 个带 YAML front matter。样本同时包含单语言英文与中文参考站、双语产品站、发布归档、 自定义落地页，以及独立的 Book 消费站。 盘点刻意测量源码 Markdown，而不是生成后的 HTML。统计项包括 shortcode …

决策 OINK 保留 Hugo 原生键与仍有价值的 Docsy 兼容键，把主题呈现和行为放在 params.ui.* 下，并用同名的顶层 front matter 键提供页面覆盖。它不增加 params.oink.* 配置树，也不建立一套遮蔽 Hugo 配置模型的注册表。 背景 OINK 继承了成熟的配置面，又增加了阅读外壳、内容输出和本地交互。早期设计曾尝试把所有 主题自有键迁入一个新命名空间，并在每页一次性解析完整配置字典。这样会在 Hugo 原生键旁边 再造一种语言，使 section …

PRD 草案，只记录剩余工作 OINK 已经具备共享正文图片 resolver、单一 Zoom marker、可处理的 Markdown 图片、编号 figure 与安全的 Landing URL 处理。本页只提议尚未解决的收敛问题，不能把它读成“当前缺失功能清单”。 当前基线 正文图片钩子、编号 fig、卡片与 gallery 统一通过 content/image-resolve.html 解析页面资源、 section 资源、全局资产、static 文件与显式远程 URL。栅格资源可以提供 …

PRD 草案，尚未实现 OINK 当前没有 backlink 区块、局部图谱、全站图谱页或 graph 输出格式。提案中的名称和配置在 提案被接受、契约发生变化之前都不是公开 API。 前提 反向导航与页面连接视图是链接图的属性，不是 [[wikilink]] 拼写的属性。Hugo 已经接受普通 Markdown 链接和 ref / relref。OINK 可以从作者已经在写的内容中派生图谱，无需增加解析器、 Goldmark 扩展或并行创作语法。 首要价值是反向链接，而不是可视化。静态入链列 …

决策 OINK 不调用 Hugo 的 errorf。作者或站点输入无效时，主题发出警告，并使用文档中 明确的安全回退，或者省略无效片段。版本发布与部署构建使用 --panicOnWarning， 因此同一条警告在发布门禁中仍会导致硬失败。 背景 Hugo 把整座站点作为一次事务构建。编辑一页时触发的 errorf 会让该次重建中的所有 URL 都返回错误，包括无关页面和首页。服务器进程仍然存在，修正输入后也会自动恢复，但多人共享 的预览在此期间完全不可用。 警告的开发成本不同。出错的值可以回退 …

OINK 0.6.0 契约 这是随 OINK 0.6.0 正式发布的架构契约。本页是权威中文源文件，与英文版本 一同维护在 content/docs/design/。 仓库与装配 仓库根目录是一个完整的 Hugo 模块与主题，不是站点，也不是 npm workspace。 Hugo Extended 负责编译 SCSS 与模板。浏览器运行时与第三方资源都已提交到仓库， 因此普通构建不会访问网络。公开的双语文档、示例与浏览器测试位于同级的 oink.pgsty.com 仓库；主题仓库只在 …

已验证快照 这些探针在 Hugo Extended 0.160.1 与 0.164.0 上得到字节一致的相关输出。它们解释 OINK 的原生组件形态；当前组件契约仍是权威。 方法 探针使用一个不带 OINK 模板的最小 Hugo 站点。渲染钩子把上下文字段与 .Attributes 输出为 可见标记。站点开启 Goldmark 块属性、行内与块级数学 passthrough 分隔符，以及为检查原始 HTML 而刻意启用的 unsafe 渲染，并设置 …