# 页面参数

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

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

本页是页面级参数的全表，只列 OINK 主题会读取的键。Hugo 自身的 front matter 字段（`slug`、`url`、`build`、`sitemap`、`expiryDate` 等）照常可用，语义见 [Hugo 文档](https://gohugo.io/content-management/front-matter/)。站点级参数（`hugo.yml` 里的 `params.*`）见[配置总览](/zh/docs/customize/config/)。

## 表格说明 {#how-to-read}
优先级从高到低：

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

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

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

```yaml {title="content/docs/wide-reference.zh.md"}
---
title: 兼容性矩阵
weight: 40
page_width: wide
footer_style: slim
image_zoom: true
section_index: list
---
```

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

```yaml {title="content/docs/reference/_index.zh.md"}
cascade:
  pager: false
  section_index: list
```

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

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

## 基本 {#basic}

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

## 侧栏与导航 {#navigation}

指南在[组织内容](/zh/docs/write/organize/)。

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

## 页面外壳 {#shell}

站点级的默认值与效果说明在[布局与页面类型](/zh/docs/customize/layout/)。

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

## 搜索 {#search}

指南在[全文检索](/zh/docs/customize/search/)。

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `search_keywords` | 字符串或字符串数组 | — | 附加检索词，包含中英文与同义词 |
| `search_boost` | 正数 | `1.0` | 排序乘数，最终得分为文本匹配分乘以该值。非数字、非有限、零或负值告警并回退 `1.0` |
| `search_exclude` | 布尔 | `false` | 不进本地索引 |
{.fields meta="type default"}

## 输出形态 {#outputs}

指南在 [Agent 支持](/zh/docs/customize/agents/)（`.md` 与 `llms.txt`）与[打印支持](/zh/docs/customize/print/)。

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `outputs` | 字符串数组 | 站点 `outputs` | 这一页生成哪些输出格式；写 `[HTML]` 时不再生成 `.md` |
| `no_print` | 布尔 | `false` | 不进入整章 / 整书的聚合打印输出 |
{.fields meta="type default"}

## 页尾：评论、反馈与出处 {#page-end}

顺序固定为反馈 → 出处 → 翻页器 → 评论，见[编写页面](/zh/docs/write/pages/#page-end)。

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `comments` | 布尔 | 站点 `params.comments.enable`（`false`） | 本页是否显示 giscus 评论区，见[启用评论](/zh/docs/admin/comments/) |
| `feedback` | 布尔或映射 | 站点 `params.ui.feedback`（关） | 映射形态支持 `enable` 与 `reasons`。其它写法告警并回退 |
| `annotation` | 布尔 | 站点 `params.ui.annotation`（开） | 页尾的「最后修改 / 出处」区块。只接受布尔，其它写法告警并回退 |
| `translation_notice` | 语言代码或 `false` | 站点 `params.ui.translation_notice`（关） | 权威版本的语言代码，译文据此显示一条指回原文的说明；本页即以本语言原创时写 `false` |
{.fields meta="type default"}

### 上游出处 {#upstream}

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

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

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

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

## 图片缩放 {#image-zoom}

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `image_zoom` | 布尔 | 站点值（`false`） | 本页的图片是否可点击放大，见[图片](/zh/docs/components/image/)。非布尔告警并回退 |
{.fields meta="type default"}

## 博客与文章 {#blog}

指南在[博客与文章](/zh/docs/write/blog/)。

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

## Book {#book}

指南在[书籍出版](/zh/docs/write/book/)。整本书通过栏目 `cascade` 设 `type: book`。

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

## Landing {#landing}

指南在[首页与落地页](/zh/docs/customize/home/)。任意页面写 `layout: landing` 就用落地页外壳。

| 键 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `landing` | 字符串 | — | 数据取自 `data/landing/<key>/<语言>.yaml` |
| `sections` | 数组 | — | 在 front matter 里内联分区定义，优先于 `landing`。不是数组时构建失败 |
{.fields meta="type default"}

## 发布页 {#releases}

指南在[发布与下载页](/zh/docs/write/releases/)。栏目写 `layout: releases` 后忽略 `weight`，按发布日期与 SemVer 倒序排列。

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

## 相关 {#related}

- [编写页面](/zh/docs/write/pages/) — 每页都要写的那几个键
- [组织内容](/zh/docs/write/organize/) — 侧栏与导航键的实际效果
- [配置总览](/zh/docs/customize/config/) — `hugo.yml` 里的站点参数全表