页面参数

front matter 全表：主题真正读取的每一个页面键，按侧栏、外壳、搜索、输出、页尾、Book、Landing、发布页分组。

创作内容

本页是页面级参数的全表，只列 OINK 主题会读取的键。Hugo 自身的 front matter 字段（slug、url、build、sitemap、expiryDate 等）照常可用，语义见 Hugo 文档。站点级参数（hugo.yml 里的 params.*）见配置总览。

表格说明

优先级从高到低：

页面自己的 front matter；
最近一层 cascade（多层 cascade 都设了同一个键时，离页面最近的那一层生效）；
hugo.yml 里的站点参数。

「默认」列标「站点值」的键，未写时回落到同名的站点参数。

页面键一律写在 front matter 顶层，键名是站点键去掉 ui. 前缀：站点的 params.ui.section_index 对应页面的 section_index。front matter 里不写 ui: 段，键一律在顶层。写在 ui: 段里的键不会被读取，也不会有任何提示——某个设置看着没生效时，先对照本页核一遍键名。

---
title: 兼容性矩阵
weight: 40
page_width: wide
footer_style: slim
image_zoom: true
section_index: list
---

放进 cascade 时键名不变，多包一层：

cascade:
  pager: false
  section_index: list

非法值不会中断构建。主题会发一条警告，指出键名、收到的值以及实际用了哪个回退值，然后按表里的默认值把这一页渲染出来——一个笔误只降级一个设置，而不是让 hugo server 下每个 URL 都返回 HTTP 500。它也不会因此混进线上：所有发布关卡都带 --panicOnWarning 构建，那条警告在真正要紧的地方仍然是硬失败。

少数几个键确实会中断构建，表里会写明。它们是那种「继续构建就会发布出错误内容」而不只是「发布出朴素内容」的情形：残缺的上游署名（半条声明读起来和完整的一模一样）、translation_notice、release 事实、落地页的 sections，以及任何解析不到目标的引用。

基本

title , 字符串 , default—: 页面大标题、浏览器标题、搜索结果标题。每页必写
linkTitle , 字符串 , defaulttitle: 侧栏、面包屑、翻页器、卡片里的短名
description , 字符串 , default—: 一句话摘要：栏目卡片、搜索摘要、meta description；博客页里渲染成正文上方的导语
weight , 整数 , default0: 同级排序，用 10 的倍数；0（不写）排在所有写了 weight 的页面之后，见组织内容
draft , 布尔 , defaultfalse: 草稿不进构建产物，hugo server -D 可预览，见编写页面
date , 日期 , default—: 博客日期、发布页排序依据；未来日期默认不构建
lastmod , 日期 , defaultGit 提交时间: 页尾「最后修改」；站点启用 enableGitInfo 时不必手写
aliases , 字符串数组 , default—: 旧路径重定向到本页；用于页面迁移，不用于日常导航
type , 字符串 , default顶层目录名: 决定模板与外壳：docs book blog swagger，见组织内容
layout , 字符串 , default—: 为单个页面指定布局：landing、releases
cascade , 映射 , default—: 把下面这些键下推给整棵子树

指南在组织内容。

icon , Font Awesome class 对 , default—: 侧栏、栏目卡片与搜索结果的图标，例如 fa-solid fa-rocket
toc_hide , 布尔 , defaultfalse: 不出现在侧栏树里，也不进翻页序列
hide_summary , 布尔 , defaultfalse: 不出现在栏目首页的子页索引里
sidebar_divider , 布尔 , defaultfalse: 这一行渲染成侧栏分组标题：不是链接，也不进翻页序列
sidebar_expanded , 布尔 , defaultblog 栏目 true，其余 false: 这个栏目在侧栏里默认展开
sidebar_root_for , self / children , default—: 让这个栏目成为侧栏树的根；self 连同栏目首页，children 只管后代。其它取值告警并忽略
sidebar_root_link_self , 布尔 , defaulttrue: 根那一行链接自身；false 改为链接父栏目。非布尔构建失败
sidebar_root_menu , 布尔 , defaulttrue: 顶层栏目是否出现在根切换器里
toc_root , 布尔 , defaultfalse: 侧栏根是站点首页时，把这个顶层栏目整个排除在树与翻页序列之外
manual_link , URL , default—: 侧栏与栏目索引里这一行指向别处
manual_link_relref , 内容引用 , default—: 同上，但用 relref 解析；目标不存在时构建失败
manual_link_title , 字符串 , defaulttitle: 手动链接的悬停标题
manual_link_target , 字符串 , default—: 例如 _blank，主题自动补 noopener
no_list , 布尔 , defaultfalse: 栏目首页不生成子页索引
simple_list , 布尔 , defaultfalse: 子页索引渲染成紧凑的项目符号列表
section_index , list / cards , default站点值（list）: 子页索引的样式。非法值告警并回退
section_index_columns , 整数 , default2: 卡片样式的列数
notoc , 布尔 , defaultfalse: 不显示右栏页面目录
pager , 布尔 , default由 params.ui.pager_types 决定: false 关闭本页的上一页 / 下一页。非布尔告警并忽略该覆盖
navbar_enabled , 布尔 , default站点值（true）: 这一页是否渲染顶栏
navbar_autohide , 布尔 , default站点值（false）: 顶栏在指针设备上自动隐藏
page_context_menu , 布尔 , default站点值（true）: 标题行的页面操作菜单（复制 Markdown、编辑本页、打印……）
page_context_menu.assistant_links , 布尔 , default站点值（false）: ChatGPT / Claude 交接项，写成 page_context_menu: { assistant_links: false }。页面只能收窄站点策略，不能单独开启

页面外壳

站点级的默认值与效果说明在布局与页面类型。

page_width , normal / wide / full , defaultnormal: 正文栏宽度。非法值告警并回退
reading_width , slim / normal / wide , defaultnormal: Book 页的阅读行宽，只对 type: book 生效
footer_style , fat / slim / none , default站点值（fat）: 页脚形态。非法值告警并回退
body_class , 字符串 , default—: 追加到 <body> 上的 class，供站点自己的 CSS 使用
reading_time , 布尔 , default站点值: 本页是否显示阅读时长；写 false 关掉
sidebar_enabled , 布尔 , defaulttrue: 这一页是否显示左侧栏；写 false 关掉
scroll_spy , 布尔 , default站点值: 目录的滚动跟随；写 true 打开
keyboard_nav , 布尔 , default站点值（true）: 单键键盘导航，见键盘导航。非布尔告警并回退
lastmod_commit , subject / hash / none , defaultsubject: 「最后修改」后面怎么显示提交。非法值告警并回退
sidebar_expand_levels、sidebar_menu_compact、sidebar_menu_foldable、sidebar_item_overflow , 同站点参数 , default站点值: 侧栏行为也可以逐页覆盖；取值见配置总览

搜索

指南在全文检索。

search_keywords , 字符串或字符串数组 , default—: 附加检索词，包含中英文与同义词
search_boost , 正数 , default1.0: 排序乘数，最终得分为文本匹配分乘以该值。非数字、非有限、零或负值告警并回退 1.0
search_exclude , 布尔 , defaultfalse: 不进本地索引

输出形态

指南在 Agent 支持（.md 与 llms.txt）与打印支持。

outputs , 字符串数组 , default站点 outputs: 这一页生成哪些输出格式；写 [HTML] 时不再生成 .md
no_print , 布尔 , defaultfalse: 不进入整章 / 整书的聚合打印输出

页尾：评论、反馈与出处

顺序固定为反馈 → 出处 → 翻页器 → 评论，见编写页面。

comments , 布尔 , default站点 params.comments.enable（false）: 本页是否显示 giscus 评论区，见启用评论
feedback , 布尔或映射 , default站点 params.ui.feedback（关）: 映射形态支持 enable 与 reasons。其它写法告警并回退
annotation , 布尔 , default站点 params.ui.annotation（开）: 页尾的「最后修改 / 出处」区块。只接受布尔，其它写法告警并回退
translation_notice , 语言代码或 false , default站点 params.ui.translation_notice（关）: 权威版本的语言代码，译文据此显示一条指回原文的说明；本页即以本语言原创时写 false

上游出处

页面改写自别处的材料时，用 upstream_link 声明来源，页尾出处行会给出作品、版权人、许可证与完整声明的链接。这一族键的解析顺序是站点参数 → data/upstreams 中由 upstream_source 指名的条目 → 本页 front matter，最具体的声明胜出。

upstream_link 只从 front matter 读取（cascade 有效，站点参数无效）——站点级的值会让每一页都声称同一个来源。没有 upstream_link 却写了任何一个同族键，构建失败。

upstream_link , URL , default—: 本页据以改写的材料地址。写空串退出 cascade 继承来的值
upstream_name , 字符串 , default—: 上游作品名，按上游自己的写法。设了 upstream_link 即必填
upstream_copyright , 字符串 , default—: 版权声明，保留上游原文。必填
upstream_license , SPDX 标识 , default—: 必须能在 data/licenses 中查到，否则构建失败。必填
upstream_notice , 站内路径或 URL , default—: 承载完整声明（许可证全文、免责声明、上游 NOTICE、快照版本）的页面。必填
upstream_ref , 字符串 , default—: 快照对应的 tag 或 commit，显示在作品名后的括号里
upstream_source , 字符串 , default站点参数: data/upstreams 中的条目名，用于集中声明多页共用的上游事实；条目不存在构建失败
upstream_modified , 布尔 , defaultfalse: 页尾追加一条「本地已修改」；站点配了仓库信息时带「查看历史」链接。非布尔构建失败

四个必填键（upstream_name、upstream_copyright、upstream_license、upstream_notice）缺一即构建失败：残缺的署名比明显的缺失更糟。主题自带一份 SPDX 表 data/licenses.yaml，站点用同名文件补充或覆盖条目。

图片缩放

image_zoom , 布尔 , default站点值（false）: 本页的图片是否可点击放大，见图片。非布尔告警并回退

博客与文章

指南在博客与文章。

author , 字符串 , default—: 文章署名，支持行内 Markdown。页面写了 authors 时忽略它
authors , 字符串数组 , default—: authors taxonomy 的 term，顺序即署名顺序，见作者与署名。需要在 taxonomies: 下声明 author: authors
series , 字符串数组 , default—: series taxonomy 的 term。正文上方的横幅取第一个，见系列
series_weight , 整数 , default—: 在系列中的位置。带权重的成员按升序排在前，其余按日期升序跟在后
tags , 字符串数组 , default—: 标签，见分类体系
categories , 字符串数组 , default—: 分类，同上
images , 字符串数组 , default—: 第一项作为文章封面与分享卡片；写进栏目 _index.md 的 cascade 即为栏目级默认，images: [] 表示不要封面
featured_image , none / banner / wash , default站点值（none）: 本文正文里怎么渲染自己的题图。非法值告警并回退
blog_index , list / cards , default站点值（list）: 写在博客根目录上，决定该栏目列表页的形态。非法值告警并回退
share , 字符串数组或 false , default站点 params.ui.share（空）: 页尾分享目标，整体替换继承来的列表；false 让本页退出，见分享。未知目标告警并丢弃
summary , 字符串 , default—: 标签 / 分类页上文章行的摘要回退来源，description 优先

Book

指南在书籍出版。整本书通过栏目 cascade 设 type: book。

book_number , 字符串 , default—: 章节编号，显示在页面标题与侧栏条目前面
book_status , draft , default—: 标记草稿章节：侧栏与目录里带草稿标记，索引里默认不列
sidebar_headings , false / true / 2–4 的整数 , default站点值（false）: 在侧栏当前条目下展开 h2–h4 分支。超出范围告警并回退
book_draft_banner , 布尔 , default站点值（false）: 草稿章节正文开头加一条横幅。非布尔告警并回退

Landing

指南在首页与落地页。任意页面写 layout: landing 就用落地页外壳。

landing , 字符串 , default—: 数据取自 data/landing/<key>/<语言>.yaml
sections , 数组 , default—: 在 front matter 里内联分区定义，优先于 landing。不是数组时构建失败

发布页

指南在发布与下载页。栏目写 layout: releases 后忽略 weight，按发布日期与 SemVer 倒序排列。

release , 字符串或映射 , default—: 发布事实。字符串形态是 https://github.com/<owner>/<repo>/releases/tag/<tag>；映射形态的键是 product version repo tag date prev checksums，version 与 repo 必填，未知键或类型不符构建失败
release_products , 字符串或字符串数组 , default—: 发布列表只保留这些产品。非法过滤条件构建失败
release_group_by_product , 布尔 , defaultfalse: 按产品分组；开启后每一篇被选中的文章都必须写 release.product

编写页面 — 每页都要写的那几个键
组织内容 — 侧栏与导航键的实际效果
配置总览 — hugo.yml 里的站点参数全表

加载评论需要启用 JavaScript。在 GitHub 上查看讨论。