配置总览
站点参数的唯一归属页。主题读取的每个键在下面某张表里有一行,给出类型、默认值与一句说明,并链接到讲它的指南页。指南页只给可粘贴的片段,不重复定义。页面级参数(front matter)见页面参数。
表格按功能分组,每组一个 ##,锚点可以引用,例如 /zh/docs/customize/config/#sidebar。默认值一栏空着表示主题没有默认值:不配置该功能就不生效。
hugo.yml 的分层
OINK 站点配置有四类键,改哪一层取决于改动目标:
| 层 | 例子 | 谁定义的 |
|---|---|---|
| Hugo 原生顶层键 | baseURL title languages markup outputs taxonomies module |
Hugo 本身,行为见 gohugo.io |
params 顶层 |
logo offline_search github_repo version page_width comments |
主题读取的站点级选项 |
params.ui.* |
navbar_enabled sidebar_width_min typography pager_types |
外壳、导航与阅读界面 |
params.<运行时> |
mermaid plantuml drawio markmap |
各内容运行时自己的开关与端点 |
最小的可用配置只需要前两层(包含支撑 OINK 原生 Markdown 组件的三项 Goldmark 设置):
配置原则
-
主题默认保守,只写要改的键。交互功能(本地搜索、图片缩放、评论、反馈、深浅色菜单)默认关闭,主题不替站点做策略决定。从一份「完整配置」逐条删减,比按需添加更容易留下用不上的键。
-
没有主题总开关。不存在
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。 -
有一条警告保留取值而不是丢弃它。主题读出的
theme_color若在默认画布上低于 AA 正文对比度(4.5:1),颜色照常生效——自定义画布或品牌强制色由作者决定——同时打印可以静音该告警的ignoreLogsid。要么换个更深的颜色,要么加一行配置静音。只有解析不出来的十六进制才会被丢弃并回退到默认配色。 -
主题自身从不中断构建。它的模板里没有任何
errorf:每个非法值都走上面的告警并回退。Draw.io 与 Algolia 缺少必需的服务配置时告警并保持关闭。OINK 1.4.0 的 PlantUML 本地渲染无需端点;显式填写的非法端点会告警并关闭渲染。主题不会代为连接公共服务。残缺的上游署名告警并略去整条声明,因为半条读起来和完整的一模一样。真正会中断构建的来自 Hugo 而非主题:解析不到目标的内容引用,以及低于module.hugoVersion.min的 Hugo 版本。
页面级覆盖优先级
Hugo 的 .Param 查找让大部分参数可以逐页覆盖,优先级从高到低:
- 页面自己的 front matter;
- 祖先分区
_index.md里的cascade(离页面越近越优先); - 站点
params。
写进 front matter 时要去掉 ui. 前缀。
站点上的 params.ui.reading_time 在页面里就写成 reading_time。front matter 里出现 ui:
块的话,里面的键没有人读,也没有人报错——某个设置看着没生效时,先对照页面参数核一遍键名。
分区级用 cascade 一次设定整棵子树:
覆盖用于真实的内容差异。逐页重建一套视觉系统的配置,会在主题升级后失配。
三项 goldmark 前置
Hugo 不会 把主题模块的 markup 配置合并进站点,这三项必须写在站点自己的 hugo.yml 里,否则属性行、组件 HTML 与数学公式都不工作:
缺 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。
Expo 相册
OINK 1.3.0 为默认 shell_types 列表添加了 expo,
并支持以下设置:
页面 expo 块整体替换站点块,未给出的字段使用内置默认值。
浏览器保存的布局与尺寸优先于作者默认值。完整规则见
Expo 默认值。
博客
以下设置控制博客栏目的呈现,作用于 params.ui.blog_section 指定的栏目,
可通过博客根目录的 front matter 或 cascade 按栏目覆盖。
布局指南对比了水平条目、卡片、表格与画廊。
下面的 gallery 布局与 blog_gallery 配置已随 OINK v1.4.0 发布;
四种布局都可以配置和切换。
params.ui.featured_image, ,- 文章正文里怎么渲染自己的题图:
none不渲染,banner在标题上方框出一张 16:9 的图,wash把它铺在文章头部背后、只留十分之一的不透明度,hero把它作为外壳自己的通栏背景铺开并把开头下移——单页与栏目列表页都一样。用的就是这一页在卡片与og:image里已经在用的那张图,两处不会打架。没有题图的文章在任何模式下都不渲染任何东西 params.ui.blog_index, ,list是水平条目,cards是规则图文卡片,table是紧凑表格,gallery是可点击封面组成的画廊。均按日期倒序排列;仅blog_index_toggle: false时的独立table不分页、列出整个栏目params.ui.blog_index_toggle, ,- 输出四种布局,让读者按
list→cards→table→gallery循环切换并记住选择;设为 false 时只输出配置的布局
页面或 cascade 的 blog_gallery 块整体替换站点块。缺失字段使用 wall 与
240;无效值告警并回退到这些默认值。读者保存的排布和大小优先于作者默认值,
并独立于 Expo 偏好。详见画廊形态。
作者与系列是 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 入口,见
品牌外观。
评论与反馈
params.comments.enable, ,- 站点级评论开关,页面用 front matter
comments覆盖,见启用评论
四个 giscus 必填项缺任意一个,都会告警并跳过评论区。必填字段见评论。
仓库链接与页面信息
内容运行时
Mermaid、KaTeX、ECharts、Infographic、Asciinema、Swagger UI 与 Redoc 按内容自动检测,只有用到它们的页面、且只在该页的 HTML 输出里加载,没有站点开关。需要开关或外部端点的只有这几个:
启用 PlantUML 且不配置端点时使用本地渲染;填写 svg_image_url 才选择服务端模式。
Mermaid 与本地 PlantUML 按图表是否接近视口加载引擎,共用查看器和源码导出,
无需新增配置。普通浏览器打印未渲染图时保留源码。
数学公式不需要参数,只需要 passthrough 前置。
输出格式
主题声明自定义输出格式,但 不替站点打开:要哪种就在 outputs 里写哪种。成本
较高的聚合输出与机器可读输出始终需要显式选择。
| 格式 | 产物 | 说明 |
|---|---|---|
HTML |
index.html |
交互形态,必选 |
markdown |
index.md |
每页的纯 Markdown 版本,页面操作里的「复制 Markdown」「查看源码」依赖它,见 Agent 支持 |
LLMS |
llms.txt |
主题声明的纯文本格式,通常只挂在 home |
LLMSFULL |
llms-full.txt |
顶层栏目 opt-in:按侧栏阅读顺序拼接同一份逐页 Markdown,每种语言一份全文包 |
NAVJSON |
navigation.json |
首页 opt-in:每种语言把侧栏 / 翻页使用的导航权威序列化一次,由 schema/nav.v1.schema.json 校验 |
print |
_print/index.html |
主题声明的整分区打印页,见打印支持 |
BookManifest |
book.json |
Book 根 opt-in,向 EPUB/PDF 打包工具交接的 JSON;本身不是电子书 |
RSS |
index.xml |
Hugo 原生,挂在 section 上让每个栏目都有订阅源 |
LLMSFULL 与 BookManifest 写在对应顶层栏目的 front matter outputs 中,
NAVJSON 写在 outputs.home。完整示例与限制见 Agent 支持
和书籍出版。
打印输出的两个参数:
多语言与版本
语言用 Hugo 原生的 languages 块定义,主题只读它建立的翻译关系:
写作侧的对等文件、锚点对齐与缺译回退见多语言。
版本相关参数:
params.version,- 当前站点变体的版本标识(不一定是 Git ref),见多版本
其它
通过生成式 Schema 获得编辑器补全
主题在其 schema/ 目录下携带两个生成的 JSON Schema:校验站点 hugo.yaml 的
site-params.schema.json 与校验页面 front matter 的
front-matter.schema.json。它们是主题自身 hugo.yaml 默认值(注释即悬浮文档)
与参数扫描注册表的投影;主题 CI 会重新生成并检查漂移。使用时应选择与主题固定版本
相同标签下的 Schema。
配合 VS Code YAML 扩展,在设置中映射站点 Schema。下面以 OINK v1.5.1 为例,
请将标签换成 go.mod 中固定的版本;两种常见 YAML 配置文件名都已覆盖:
验证关联是否生效时,可暂时把 params.offline_search 这类已知布尔键写成字符串,
确认编辑器提示类型不匹配后恢复正确值。front matter 补全取决于你的 Markdown
工具链,用同样方式指向 front-matter.schema.json 即可。
front-matter Schema 刻意不带类型约束,因为 share、theme_color 这类键在常规
类型之外还接受裸布尔退出。
验证配置变更
改完配置跑一次生产构建:
输出 Total in … 且没有 ERROR 即可。常见告警与原因:
| 告警片段 | 原因 |
|---|---|
invalid params.ui.typography |
预设只有 technical 与 system |
invalid footer_style … (allowed: fat | slim | none) |
页脚形态写错,告警会指出是哪个页面 |
invalid page_width … (allowed: normal | wide | full) |
页宽写错 |
invalid params.ui.section_index … (allowed: list | cards) |
栏目首页样式写错 |
invalid params.offline_search_index |
索引范围只有 title heading summary content |
params.drawio.enable requires an explicit params.drawio.drawio_server |
开了 Draw.io 却没给服务地址 |
params.search.algolia requires explicit appId, apiKey, and indexName |
Algolia 三项必须齐全 |
params.ui.image_zoom must be a boolean |
写成了字符串 "true" |
theme_color … is not a #rgb or #rrggbb hex color |
值不是十六进制颜色,保留默认配色 |
theme_color … reads at about N:1 against the theme's … canvas |
建议性告警:颜色照常生效,消息里带着让它闭嘴的 id |
theme_color_dark … has no theme_color to pair with |
只设了暗色一半而没有有效的 theme_color;该值被忽略,两种模式都保留默认配色 |
command … must define exactly one of url or action |
自定义命令同时给了 url 和 action,或两个都没给 |
invalid params.ui.sidebar_icon_policy …; using all |
只是警告,但取值拼错了 |
配置改动还要至少验证三件事:每种语言各一页、缺译页的回退、生产 baseURL 下的链接(子路径部署容易漏)。
主题要求 Hugo Extended 0.168.0 及以上版本。配置改动请使用固定基线验证:
最低版本写在主题的 hugo.yaml 与 theme.toml 里,站点自己的
module.hugoVersion.min 应与它一致。
相关
- 品牌外观 — 站名、Logo、配色、字体
- 导航与菜单 — 顶栏菜单、页面操作、页脚
- 布局与页面类型 — 外壳、侧栏、目录
- 页面参数 — front matter 全表
- 排错与检查 — 构建失败时怎么定位