配置总览

站点参数的唯一归属页。主题读取的每个键在下面某张表里有一行，给出类型、默认值与一句说明，并链接到讲它的指南页。指南页只给可粘贴的片段，不重复定义。页面级参数（front matter）见页面参数。

表格按功能分组，每组一个 ##，锚点可以引用，例如 /zh/docs/customize/config/#sidebar。默认值一栏空着表示主题没有默认值：不配置该功能就不生效。

hugo.yml 的分层

OINK 站点配置有四类键，改哪一层取决于改动目标：

最小的可用配置只需要前两层：

title: 产品文档
baseURL: https://docs.example.com/
defaultContentLanguage: zh
enableGitInfo: true

module:
  imports:
    - path: github.com/pgsty/oink
  hugoVersion:
    extended: true
    min: 0.160.1

params:
  offline_search: true
  github_repo: https://github.com/example/product-docs

配置原则

• 主题默认保守，只写要改的键。交互功能（本地搜索、图片缩放、评论、反馈、深浅色菜单）默认关闭，主题不替站点做策略决定。从一份「完整配置」逐条删减，比按需添加更容易留下用不上的键。

• 没有主题总开关。不存在 oink.enabled，也没有 params.oink.* 命名空间，更没有在「Docsy 外壳」与「OINK 外壳」之间切换的选项。这一页查不到的开关即不存在。

• 非法值告警并回退到文档里写明的默认值。params.ui.typography: solarized 报 invalid params.ui.typography "solarized" (allowed: technical | system) -- using "technical"，站点照常构建；footer_style: thin、page_width: huge、section_index: grid 同理。一个笔误因此只降级一个设置，而不是让 hugo server 下每个 URL 都返回 HTTP 500。它也不会因此静悄悄上线：所有发布关卡都带 --panicOnWarning 构建，那条警告在那里仍然是硬失败。

• 有一条警告保留取值而不是丢弃它。主题读出的 theme_color 若在它自己的画布上低于 AA 正文对比度（4.5:1），颜色照常生效 —— 自定义画布或品牌强制色是作者的决定 —— 但会说出来，并打印可以让它闭嘴的 ignoreLogs id。把它当建议而不是拒绝：要么换个更深的颜色，要么加一行配置，在你做出选择之前发布关卡会一直卡住构建。只有解析不出来的十六进制才会被真正丢弃，那种情况和其他非法值一样回退到默认配色。

• 主题自身从不中断构建。它的模板里没有任何 errorf：每个非法值都走上面的告警并回退。需要外部端点的功能——PlantUML、Draw.io、Algolia——缺少端点时告警并保持关闭，因为主题不会代为连接公共服务；残缺的上游署名告警并略去整条声明，因为半条读起来和完整的一模一样。真正会中断构建的来自 Hugo 而非主题：解析不到目标的内容引用，以及低于 module.hugoVersion.min 的 Hugo 版本。

页面级覆盖优先级

Hugo 的 .Param 查找让大部分参数可以逐页覆盖，优先级从高到低：

1. 页面自己的 front matter；
2. 祖先分区 _index.md 里的 cascade（离页面越近越优先）；
3. 站点 params。

写进 front matter 时要去掉 ui. 前缀。 站点上的 params.ui.scroll_spy 在页面里就写成 scroll_spy。front matter 里出现 ui: 块的话，里面的键没有人读，也没有人报错——某个设置看着没生效时，先对照页面参数核一遍键名。

---
title: 宽版参考
page_width: wide
navbar_enabled: false
footer_style: slim
scroll_spy: true
---

分区级用 cascade 一次设定整棵子树：

---
title: 文档
cascade:
  type: docs
  footer_style: slim
  feedback: true
---

覆盖用于真实的内容差异。逐页重建一套视觉系统的配置，会在主题升级后失配。

三项 goldmark 前置

Hugo 不会 把主题模块的 markup 配置合并进站点，这三项必须写在站点自己的 hugo.yml 里，否则属性行、组件 HTML 与数学公式都不工作：

markup:
  goldmark:
    parser:
      # 块级图片可以带属性行（{caption=…}、编号图）
      wrapStandAloneImageWithinParagraph: false
      attribute:
        block: true
    renderer:
      # `{{% … %}}` 型 shortcode 输出的 HTML 必须保留
      unsafe: true
    extensions:
      passthrough:
        enable: true
        delimiters:
          block: [['\[', '\]'], ['$$', '$$']]
          inline: [['\(', '\)']]
  highlight:
    # 代码高亮用 class 输出，深浅色才能各用一套配色
    noClasses: false
  tableOfContents:
    endLevel: 4

缺 attribute.block 时，{.fields} {.steps} {caption=…} 会原样显示成文字；缺 passthrough 时 \(x\) 不会变成公式；缺 unsafe 时步骤与卡片的结构会被转义。

renderer.unsafe: true 同时允许 Markdown 正文里的原始 HTML 通过，面向的是受信任的作者，不是投稿过滤器。内容来自不可信来源时，审查应放在提交流程里。

站点身份与品牌

Hugo 原生顶层键：

主题参数：

favicon 没有参数：主题按约定名扫描 static/（favicon.ico favicon.svg favicon-NxN.png apple-touch-icon.png apple-touch-icon-NxN.png），见品牌外观。

外壳类型与栏目根

外壳按 页面 type 生效，不看路径。文档可以放在任意目录，再用 cascade 给它 type: docs。

博客

七个键决定博客栏目的样子。它们作用于 params.ui.blog_section 指定的栏目，每一个都能通过博客根目录的 front matter 或 cascade 按栏目覆盖。

作者与系列是 taxonomy 而不是参数，见分类法与写博客。

顶栏与页脚

胖页脚的列数据来自 data/footer/<语言>.yaml，不是参数，见导航与菜单。

侧栏

侧栏怎么用见布局与页面类型；目录树本身由 content/ 的结构决定，见组织内容。

目录 TOC

右栏大纲的层级由 Hugo 原生配置决定，主题只控制跟踪行为：

单页隐藏大纲用 front matter notoc: true，见页面参数。

翻页与页尾

页尾组件顺序固定为分享 → 反馈 → 页面信息 → 翻页 → 评论，五者独立开关；反向链接在右栏目录旁。

搜索与命令面板

本地搜索默认关闭；打开后命令面板才会出现（顶栏放大镜、Cmd/Ctrl+ 加 K、/、\）。

自定义命令的每条记录只接受 id title description icon keywords url action 七个键；id 必须匹配 ^[a-z][a-z0-9_-]*$，且不能与内置动作 ID 重名。分语言的标题写在 languages.<lang>.params.ui.command_palette.commands。

键盘

图片缩放

哪些图片会成为缩放候选见图片。

字体排版

读者系统已有字体，或者站点已经用 @font-face 声明时，可以直接写 params.ui.fonts。随站点分发字体文件与更底层的排版调整仍走 SCSS/CSS 入口，见 品牌外观。

评论与反馈

四个 giscus 必填项缺任意一个，评论区就不渲染：不报错，也不出现。

仓库链接与页面信息

内容运行时

Mermaid、KaTeX、ECharts、Infographic、Asciinema、Swagger UI 与 Redoc 按内容自动检测，只有用到它们的页面、且只在该页的 HTML 输出里加载，没有站点开关。需要开关或外部端点的只有这几个：

数学公式不需要参数，只需要 passthrough 前置。

输出格式

主题声明自定义输出格式，但 不替站点打开：要哪种就在 outputs 里写哪种。成本 较高的聚合输出与机器可读输出始终需要显式选择。

outputs:
  home: [HTML, markdown, LLMS, NAVJSON]
  page: [HTML, markdown]
  section: [HTML, RSS, print, markdown]

LLMSFULL 与 BookManifest 写在对应顶层栏目的 front matter outputs 中， NAVJSON 写在 outputs.home。完整示例与限制见 Agent 支持 和书籍出版。

打印输出的两个参数：

多语言与版本

语言用 Hugo 原生的 languages 块定义，主题只读它建立的翻译关系：

写作侧的对等文件、锚点对齐与缺译回退见多语言。

版本相关参数：

其它

通过生成式 Schema 获得编辑器补全

主题在其 schema/ 目录下携带两个生成的 JSON Schema：校验站点 hugo.yaml 的 site-params.schema.json 与校验页面 front matter 的 front-matter.schema.json。它们是主题自身 hugo.yaml 默认值（注释即悬浮文档） 与参数扫描注册表的投影；主题 CI 会重新生成并在漂移时失败，因此它们永远不会与你 pin 的主题版本相左。

配合 VS Code YAML 扩展，在设置中映射站点 Schema：

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/pgsty/oink/main/schema/site-params.schema.json": "hugo.yaml"
  }
}

把 URL 里的 main 换成你的发布 tag，与 go.mod 的 pin 保持一致。front matter 补全取决于你的 Markdown 工具链，用同样方式指向 front-matter.schema.json 即可。 front-matter Schema 刻意不带类型约束，因为 share、theme_color 这类键在常规 类型之外还接受裸布尔退出。

验证配置变更

改完配置跑一次严格构建：

hugo --printPathWarnings --panicOnWarning

输出 Total in … 且没有 ERROR / WARN 才算通过。常见报错与原因：

配置改动还要至少验证三件事：每种语言各一页、缺译页的回退、生产 baseURL 下的链接（子路径部署容易漏）。

主题声明的 Hugo 下限是 0.160.1。OINK 的持续测试工具链固定为 Hugo Extended 0.165.0；配置改动只使用这个固定版本测试一次，不再运行版本矩阵：

# 输出必须包含 v0.165.0+extended
hugo version
hugo --printPathWarnings --panicOnWarning

下限版本写在主题的 hugo.yaml 与 theme.toml 里，站点自己的 module.hugoVersion.min 应与它一致。它仍是消费站兼容性声明，不再是第二个常规 CI 测试项。

相关

• 品牌外观 — 站名、Logo、配色、字体
• 导航与菜单 — 顶栏菜单、页面操作、页脚
• 布局与页面类型 — 外壳、侧栏、目录
• 页面参数 — front matter 全表
• 排错与检查 — 构建失败时怎么定位