定制站点

• 1: 配置总览
• 2: 品牌外观
• 3: 首页与落地页
• 4: 导航与菜单
• 5: 布局与页面类型
• 6: 全文检索
• 7: 命令面板
• 8: 键盘导航
• 9: 多语言
• 10: 多版本
• 11: 分类体系
• 12: 仓库与页面信息
• 13: 打印支持
• 14: Agent 支持

1 - 配置总览

站点参数的唯一归属页。主题读取的每个键在下面某张表里有一行，给出类型、默认值与一句说明，并链接到讲它的指南页。指南页只给可粘贴的片段，不重复定义。页面级参数（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 全表
• 排错与检查 — 构建失败时怎么定位

2 - 品牌外观

本页覆盖站点外观：站名与 Logo 写在 hugo.yml，配色与字体走 SCSS 入口，页宽与页脚形态是参数。前提是站点已能构建（十分钟上手）。

需要改动的文件有四个：hugo.yml、static/ 下的图标、assets/scss/_variables_project.scss、assets/scss/_styles_project.scss。不要改主题目录里的文件：主题是 Hugo Module，升级时整个目录会被替换。

站名

站名出现在顶栏、浏览器标题与页脚。多语言站每种语言各写一个：

title: 产品文档

languages:
  en:
    title: Product Docs
    label: English
    locale: en-US
    weight: 1
  zh:
    title: 产品文档
    label: 简体中文
    locale: zh-CN
    weight: 2

顶层 title 是兜底，languages.<lang>.title 优先。

Logo 与字标

主题默认使用自带的 assets/icons/logo.svg。替换步骤是把图标文件放进站点的 assets/ 或 static/，再在配置里指向它。

params:
  logo: images/product-mark.svg
  wordmark: logo.svg

• params.logo 是方形图标，顶栏、侧栏与页脚共用。放在 assets/ 下会经过 Hugo 资源管线（可指纹化），放在 static/ 下按原样发布；两种写法都是相对 assets/、static/ 根的路径。
• params.wordmark 是横向字标。设置后顶栏用它替代「图标 + 站名」，窄屏放不下时回落到 params.logo。不设置则保持「图标 + 站名」。

源 SVG 应紧贴图形边缘裁切，否则各处尺寸对不齐。SVG 必须带 viewBox，颜色继承 currentColor，或者在深浅色下都有足够对比度。

本站两个参数都不设：顶栏用主题自带的 assets/icons/logo.svg 搭配以展示字体渲染的站名。

favicon

favicon 没有参数。主题扫描站点 static/ 目录里的约定文件名，发现哪个就在每个页面输出对应的 <link>：

够用的最小组合是 favicon.ico + favicon.svg + apple-touch-icon.png。带尺寸后缀的文件必须是正方形（NxN），否则不会被识别。

这些文件用任意图形工具生成即可。主题不需要 Node.js，Hugo 只发布 static/ 里已经存在的文件。

Web App Manifest 一类的额外 head 元数据不在扫描范围内，用 layouts/_partials/hooks/head-end.html 钩子自行输出；要改变发现规则本身（换目录、增加文件名），在站点 layouts/ 下覆盖 layouts/_partials/favicons.html。

主色与配色

配色分两层：Bootstrap 的语义色（编译期 Sass 变量）和 OINK 的品牌层（运行期 CSS 自定义属性）。

先改语义色，它决定按钮、链接、提示块的色调：

$primary: #315f8f;
$secondary: #b4762e;
$success: #2c7a4b;
$warning: #9a6700;
$danger: #b42318;

这个文件在 Bootstrap 与 OINK 默认值 之前 加载，是覆盖 Sass 变量的位置。需要引用 Bootstrap 已定义的变量或 map 时，改用 _variables_project_after_bs.scss。

品牌层是一组 CSS 自定义属性，浅色和深色 必须成对覆盖，否则一种模式下会漏色：

:root {
  --td-brand-copper: #a66722;
  --td-brand-mark-from: #1d588c;
  --td-brand-mark-to: #a66722;
}

[data-bs-theme='dark'] {
  --td-brand-copper: #e0a35c;
  --td-brand-mark-from: #7fb8e8;
  --td-brand-mark-to: #e0a35c;
}

可覆盖的品牌属性有 --td-brand-elev（浮层底色）、--td-brand-silk（次要文字）、--td-brand-copper 与 --td-brand-copper-dim（强调色与它的弱化版）、--td-brand-line-strong（分隔线）、--td-brand-header-bg（顶栏背景）、--td-brand-shadow-sm / --td-brand-shadow-md（阴影）、--td-brand-mark-from / --td-brand-mark-to / --td-brand-mark-gradient（品牌渐变）。

分区主题色

上面的品牌配色决定整站的颜色。theme_color 是它旁边一件更小的乐器：一个十六 进制色，为外壳的强调底着色，让读者不用被告知也知道自己身在站点的哪一块。

params:
  ui:
    theme_color: '#6d28d9'
    theme_color_dark: '#a78bfa' # 可选

它按分区写比按站点写有用得多。写进分区根的 cascade，整个分区就有了身份 —— 藏青的文档、紫色的博客、橙色的教程 —— 而站点默认仍是品牌色：

cascade:
  theme_color: '#6d28d9'
  theme_color_dark: '#a78bfa'

Hugo 会把这些 cascade 值同时解析到分区首页与子页，因此只声明这一对即可。同一对 解析结果既驱动页面强调色，也驱动根切换器里该分区的图标。

它作用于：侧栏选中行、以及指针划过其它行时那一层更灰的底、hover 淡铺、 页面目录的药丸与那条会走的轨道和光点、指针落在其上的 Book 章节小标题、标签与 徽章的 hover、内容卡片 hover 时的外边、分享按钮 hover 时的实心底、文本选中、 焦点环，以及侧栏根切换器里每个分区的图标。

它刻意不作用于：正文链接、外链、行内代码。这些是阅读约定，不是品牌表面 —— 一页密集的标识符在任何分区都该读成「代码与正文」，链接在哪里都该看起来像链接。 这也是强调色单独占一个自定义属性、而不是去重刷 Bootstrap 链接色的原因。

暗色一半是可选的。省略时，从亮色向白提亮，直到在暗色画布上达到 AA 正文对比度， 所以只填一个颜色的作者不可能产出不可读的暗色配色。派生结果不再符合期望的品牌 色相时，再自己指定暗色一半。亮色才是主键：单独设置 theme_color_dark，或者把它放在 一个非法的 theme_color 旁边，两种模式都不会着色 —— 主题会发出警告并保留默认配色， 而不是只给暗色模式上色。

彩色栏目里的某一页可以用主题的裸布尔惯例谢绝颜色：front matter 写 theme_color: false 即让该页退出继承的栏目色（含继承的暗色一半），静默回到默认 配色，不产生警告。其他非十六进制取值（数字、true、颜色名）都会告警。

Hugo 按键合并参数：某一页在同时设了 theme_color_dark 的分区里只覆盖 theme_color，会继承那个暗色。要么两个都覆盖，要么都不覆盖。

深浅色模式

主题默认 不显示 深浅色控件。开启方式：

params:
  ui:
    dark_mode: true

开启后顶栏出现一个主题控件：点击在浅色与深色之间切换，悬停或键盘聚焦展开「跟随系统 / 浅色 / 深色」。读者的选择存在浏览器本地，没有选择时跟随 prefers-color-scheme。切换脚本在首屏绘制前设置好 data-bs-theme，不会出现主题闪烁。

只要深色调色板、不要控件时写 dark_mode: { show_menu: false, enable: true }；dark_mode: false（默认）两者都不启用。

自定义组件在两种模式下都要给出可读的悬停、聚焦、禁用、选中状态，正文对比度至少 4.5:1、大号文字 3:1。

字体

字体有两档预设，在构建期决定，不涉及 JavaScript：

params:
  ui:
    typography: technical # technical | system

• technical（默认）：界面与正文用随主题分发的 Inter（可变字重，拉丁 / 西里尔 / 希腊 / 越南语子集，中文与 emoji 落到平台字体），标题装饰用 Chakra Petch，代码用 IBM Plex Mono。字体文件都是本地的，不请求 Google Fonts。
• system：界面、展示、元数据、打印与等宽角色全部回到平台字体栈，浏览器不请求品牌字体。字体文件仍随主题分发，只是不被引用。

非法取值告警并回落到 technical，普通 hugo server 照常可用；发布门禁开着 --panicOnWarning，这类告警在那里才是硬失败。选中的值写入 <html data-td-typography="…">，可在浏览器中确认。

自定义字体

字体角色是七个 CSS 自定义属性，覆盖它们即可，不必查找组件选择器：

ui 是主字体：body 经它解析，heading 又经 body 解析，所以只写 ui 一行，界面、正文与标题一起换掉。

在配置里换

只是想换一套字体族，不必碰 SCSS，写 params.ui.fonts 即可：

params:
  ui:
    fonts:
      # 主字体：界面、正文、标题一起跟着走
      ui: "'Source Han Sans SC', 'PingFang SC', sans-serif"
      # 等宽要带中文兜底，否则中英混排的代码块会对不齐
      code: "'Sarasa Mono SC', 'Noto Sans Mono CJK SC', monospace"

这里写的是字体族名，不是字体文件。主题不会因为这个键去下载或加载任何字体：所写的族必须是读者机器上已有的，或者站点自己在样式表里 @font-face 声明过的。所以每个列表都要以通用族（sans-serif、monospace、serif）收尾——读者没有你写的字体时，落到那里。

取值只放行纯粹的字体族语法：带引号的名字、裸标识符、允许前导连字符（-apple-system），以及任何文字系统写成的名字（苹方 合法）。分号、花括号、括号、url()、尖括号一律不过关。未知角色或不合法取值只告警并单独丢弃，同一份 map 里其余的行照常生效。什么都不设时，<head> 里连这个 style 元素都不会出现。

该块在样式表之后输出，这正是作者字体能在同等优先级下压过 typography 预设的原因。

在样式表里换

要自带字体文件，或者只给某一类内容换字体，仍然走样式表。把 .woff2 放进站点 static/webfonts/，在项目样式里声明字面，再改写角色：

@font-face {
  font-family: 'My Sans';
  font-display: swap;
  font-style: normal;
  font-weight: 400 800;
  src: url('../webfonts/my-sans-variable.woff2') format('woff2');
}

:root {
  --td-ui-font-family: 'My Sans', 'Noto Sans SC', sans-serif;
  --td-body-font-family: var(--td-ui-font-family);
  --td-heading-font-family: var(--td-ui-font-family);
  --td-display-font-family: var(--td-heading-font-family);
}

角色按 CSS 规则继承，只给某类内容换字体也不必复制组件选择器：

body.td-blog {
  --td-body-font-family: 'My Serif', 'Noto Serif SC', serif;
  --td-heading-font-family: var(--td-body-font-family);
}

等宽字体要带中文兜底，否则中英混排的代码块会对不齐：

:root {
  --td-code-font-family: 'My Mono', 'Sarasa Mono SC', 'Noto Sans Mono CJK SC', monospace;
}

从 Docsy 迁移过来的站点不必改写法。旧的 Sass 变量仍然喂进对应角色，写在 _variables_project.scss 里照样生效，优先级高于预设默认值：

Docsy 的三个 Google Fonts 变量 $td-enable-google-fonts、$td-google-font-name 与 $td-web-font-path 主题已不再读取。它们留在 _variables_project.scss 里不影响构建，也不产生任何效果：随主题分发的是 Inter、Chakra Petch 与 IBM Plex Mono，两档预设都不向 Google Fonts 发请求。打印角色 --td-print-font-family 跟随正文角色，主题不为纸张单独提供字体。

YAML 里只接受字体族名。远程字体 URL 与任意 CSS 都不接受：字体文件与样式必须是可审查的本地输入，一次普通构建不会因为字体发出任何网络请求。

页宽

params:
  page_width: normal # normal | wide | full

page_width 控制外壳整体宽度，可逐页或按分区 cascade 覆盖。Book 页另有一个 reading_width（slim / normal / wide），改的是正文阅读行宽，不是外壳。 两个键取值非法都会在普通预览中告警并回退；带 --panicOnWarning 的发布构建会失败。

页脚

params:
  ui:
    footer_style: fat # fat | slim | none
  copyright:
    authors: '[产品团队](https://example.com/)'
    from_year: 2026
    to_year: present
  footer_center_info: 'Powered by [Oink](https://oink.pgsty.com)'

• fat（默认）：多列链接网格 + 版权行；
• slim：只有版权行；
• none：不渲染页脚。

页面 front matter（含分区 cascade）可以覆盖它，本站的文档栏目用的是 footer_style: slim。无法识别的取值在普通预览中告警并回退到 fat，严格发布构建 拒绝这条警告。

多列网格的数据在 data/footer/<语言>.yaml，写法见导航与菜单。配了 fat 但没有数据时自动降级成 slim，可以先开启再补内容。

params.copyright 接受 Markdown 字符串，或 authors / from_year / to_year 三键的 map（present 表示今年）。footer_center_info 是页脚中间的行内 Markdown，显式设为空字符串即隐藏中间区域。

SCSS 入口与不该做的事

站点的 SCSS 覆盖进入主题的同一个样式包，生产构建仍然只有一份带指纹与完整性校验的样式表。三个入口文件放在站点 assets/scss/ 下：

编译顺序是：Bootstrap 函数 → 项目变量 → OINK 默认值与 Bootstrap → Bootstrap 之后的项目变量 → OINK 组件与品牌层 → 项目样式。

CSS 接口有明确边界。字体那一节的七个字体角色与 --td-brand-* 品牌属性是公开接口，主题在小版本之间保持它们的名字与含义。组件别名（如 --td-asciinema-font-family）只承诺在该组件范围内有效，未在文档中记录的 --td-shell-* 一类变量是实现细节，随时可能改名或消失。

不该做的事：

• 不改主题目录里的任何文件（hugo mod 会覆盖）；
• 不单独 @import 主题的内部 partial，它们不是公开的 Sass 接口，导入顺序可能变化；
• 不为了改一个颜色去覆盖 baseof.html。有设计变量就用变量，没有再写作用域尽量小的选择器；
• 不引用远程样式表或字体 CDN。

需要额外的第三方 CSS 时，用 layouts/_partials/hooks/head-end.html 钩子发布本地资源，不在 Markdown 里写 <link>。

验证

hugo --printPathWarnings --panicOnWarning

• 构建输出 Total in …，没有 ERROR / WARN；
• 页面源码里 <html> 上有 data-td-typography="technical"（或所选的预设）；
• 浏览器中顶栏显示自己的 Logo 与站名，标签页图标是自己的 favicon；
• 切到深色模式再看一遍正文、表格、提示块、代码块与焦点框。配色改动容易只在一种模式下验证过；
• 换一种语言，确认站名随之切换。

字体是否已替换，用浏览器开发者工具查任意一段正文的 font-family：应当是自己声明的字面，而不是 Inter。

相关

• 配置总览 — 品牌相关参数的类型与默认值
• 导航与菜单 — 顶栏菜单、页面操作与页脚数据
• 布局与页面类型 — 外壳、侧栏与目录
• 图片 — 正文里的图片、深浅色双图与图注
• 首页与落地页 — Hero、分区与落地页数据

3 - 首页与落地页

首页不是模板，是一份数据：data/home/<语言>.yaml 里的 sections 列表决定页面从上到下有哪些分区，每个分区的内容在同一份文件里按名字取。普通页面加 layout: landing 也能用同一套分区。

分区全部在服务端渲染。价格、star 数、截图、头像、下载状态都必须在 Hugo 启动前就存在于仓库中，没有分区会在浏览器里取数据。

从 Docsy 的 blocks/* 首页迁移过来的站点要重写首页：主题没有 blocks/cover、blocks/section、blocks/feature 这些 shortcode，保留它们会让构建报 template for shortcode "blocks/cover" not found。两条出路是本页讲的 data/home/<语言>.yaml，或者给一个普通页面加 layout: landing。

首页的数据来源

首页的内容文件只留标题与描述：

---
title: OINK
description: 本地优先、仅依赖 Hugo 的技术文档主题
---

分区数据按语言分文件：

查找顺序是 data/home/<当前语言>.yaml → data/home/en.yaml → 单语言站点的 data/home.yaml。

文件结构只有两层：一个 sections 列表，加上被列表引用的同名键。

sections:
  - hero          # 用 hero: 键的数据
  - capabilities
  - type: cards   # 用 cards 分区，但读 release: 键的数据
    key: release
  - cta

hero: { … }
capabilities: { … }
release: { … }
cta: { … }

这是本站首页的写法，完整文件见仓库的 data/home/zh.yaml。

最小可用首页

粘贴下面这段，替换文字与链接即可发布。链接写成不带前导斜杠的站内路径，主题会补上当前语言前缀（docs/start/ → /zh/docs/start/）。

sections:
  - hero
  - cards
  - cta

hero:
  eyebrow: 本地优先 · 仅依赖 Hugo
  title_lines:
    - words:
        - { text: PGSTY OINK }
  lead: 组件写在 Markdown 里，资源随主题分发，一份内容产出四种输出。
  image:
    light: images/hero-light.webp
    dark: images/hero-dark.webp
    alt: OINK 工程文档插图
  actions:
    - { label: 十分钟上手, url: docs/start/, icon: fa-solid fa-rocket, style: primary }
    - { label: 看组件, url: docs/components/, style: ghost }

cards:
  eyebrow: 能做什么
  title: 工程文档需要的都在里面
  columns: 3
  items:
    - title: Markdown 原生组件
      desc: 提示块、标签页、参数表、文件树都是 Markdown 语法的一部分。
      icon: fa-solid fa-cubes
      url: docs/components/
    - title: 四态输出
      desc: HTML、打印、Markdown、RSS，同一份内容不丢信息。
      icon: fa-solid fa-file-export
      url: docs/customize/agents/
    - title: 本地优先
      desc: 字体、图标、搜索、图表运行时全部随主题分发，不连 CDN。
      icon: fa-solid fa-plug-circle-xmark
      url: docs/about/features/

cta:
  title: 从一个能跑的双语站点开始。
  text: 从 OINK Starter 起步，替换项目身份与内容，再发布上线。
  label: 开始使用
  url: docs/start/
  style: primary

Hero

Hero 是首屏，唯一一个带大标题与配图的分区。

hero:
  eyebrow: PROJECT 1.0 · 本地优先         # 标题上方的小字，带状态点
  title_lines:                            # 逐行控制的大标题
    - words:
        - { text: PGSTY OINK }
  lead: 一句话说清这是什么。                 # 支持行内 Markdown 与 <br>
  note: 无需 Node.js                       # 带图标的补充行
  note_icon: fa-solid fa-circle-check
  title_size: 4.25rem                     # 只接受 rem / em / px
  image:
    light: images/hero-light.webp
    dark: images/hero-dark.webp           # 只给一个时深浅色共用
    alt: 首屏插图
  media:
    ratio: '1fr 240px'                    # 文案与配图的列宽
    max_width: 240px
    hide_below: md                        # sm | md | lg | xl 以下隐藏配图
  actions:
    - { label: 开始使用, url: docs/start/, icon: fa-solid fa-rocket, style: primary }
    - { label: GitHub, url: 'https://github.com/pgsty/oink', external: true, style: ghost }
  detail: { label: 看看它长什么样, url: docs/about/showcase/ }

不写 title_lines 时用 title，两者都没有时用站点标题。配图是 CSS 背景图，alt 有值时容器带 role="img"，无值时对辅助技术隐藏。

align: center 是纯文字的居中首屏：文案块加宽居中，标题自动平衡换行，note 挪到按钮下方。两者同时出现时，普通预览会告警并回退到 start 以保留图片；严格 发布构建拒绝这条警告。

分区注册表

22 种分区，名字用连字符（旧数据里的下划线会被规范化）。除 Hero 之外，每种都共用 eyebrow / title / desc（或 text）三个抬头字段与一个 class。

写错类型名不会静默消失：构建时给一条 unknown section type 警告并跳过该分区。CI 里加上 --panicOnWarning 即变成构建失败。

常用分区的最小写法

卡片与能力面板是最常用的两种。cards 用 columns 控制列数：

cards:
  title: 应用场景
  columns: 4
  link_label: 了解详情
  items:
    - title: 书籍出版
      meta: 长篇
      icon: fa-solid fa-book-open
      desc: 编号图表式例、交叉引用、索引与整本打印。
      url: docs/write/book/

capabilities 是一屏一条能力，右边配一块结构化的视觉面板，visual.type 只能是 shell、components、code、image、card 五种之一：

capabilities:
  eyebrow: 价值主张
  title: 工程文档所需的能力，开箱即用
  items:
    - ref: 01 / 工程文档
      title: 为工程师与文档站设计
      url: docs/start/
      motto: 从第一次构建到长期维护都没有额外阻力
      bullets:
        - '开箱即用的[部署上线](docs/admin/deploy/)体验'
        - '自带[全文检索](docs/customize/search/)与[多语言](docs/customize/i18n/)'
      value: 内容团队把时间用在文档上，而不是重复搭站点。
      visual:
        type: code
        title: build.sh
        lines:
          - { class: c, prefix: '# ', text: 一条命令，一份确定性输出 }
          - { class: p, prefix: '$ ', text: hugo --gc --minify }
          - { class: ok, prefix: '✓ ', text: public/ 可以部署 }

metrics:
  title: 事实
  animate: true
  items:
    - { value: 2189, compact: true, label: Stars, source: { label: 本地 CI 数据, url: 'https://example.org/' } }
    - { value: 32, suffix: '+', label: 语言 }

command-box:
  title: 安装
  code: hugo mod get github.com/pgsty/oink
  lang: bash
  note: 复制按钮由按需加载的 Landing 运行时提供。

steps:
  title: 三步上线
  items:
    - { title: 克隆, desc: 复制文档站仓库。 }
    - { title: 配置, desc: 改三处配置。, cmd: { code: hugo server } }
    - { title: 发布, desc: 推上 GitHub Pages。 }

timeline:
  title: 项目历程
  items:
    - { date: '2024', title: 原型, desc: 第一批数据驱动分区。 }
    - { date: '2026', title: 场景组件, desc: Landing 成为可复用外壳。 }

code-plate:
  title: 页面配置
  aria_label: 示例配置
  lang: yaml
  code: |
    layout: landing
    landing: pricing

preview:
  title: 所写即所得
  file: guide.md            # 源码面板抬头里的文件名，默认 page.md
  source: |                 # 右侧用站点自己的渲染钩子渲染这段 Markdown
    > [!TIP] 只用 Markdown
    > 提示块、步骤、标签页，都是普通语法。

    1. 写 Markdown
    2. 运行 `hugo`
    {.steps}

case-study:
  title: 迁移结果
  stats:
    - { value: 12, label: 可复用分区 }
    - { value: 0, label: 远程请求 }
  quote: “一份 YAML 取代了一个定制页面模板。”
  source: 站点维护者

pricing:
  title: 价格
  tiers:
    - name: 社区版
      price: 免费
      period: 永久
      desc: 完整开源能力。
      features: [全部组件, 社区支持]
      cta: { label: 下载, url: docs/start/ }
    - name: 专业版
      featured: true
      price: ¥24K
      period: /年
      features: [优先响应, 发布包]
      cta: { label: 联系我们, url: 'mailto:example@example.org' }

pricing-compare:
  title: 档位对比
  tiers: [社区版, 专业版]
  groups:
    - name: 支持
      rows:
        - { name: 优先响应, cells: [N, Y] }
        - { name: 年费, price_row: true, cells: [免费, ¥24K] }

download:
  title: 下载
  keys: [prd5]

bar-chart:
  title: 构建耗时
  unit: 秒
  items:
    - { label: 首次构建, value: 12.3, group: cold }
    - { label: 热缓存, value: 1.6, group: warm, note: 同一台机器上的重复构建。 }

download 分区消费的就是发布与下载页里那份 data/download/<key>.yaml，不引入第二套版本模型。

任意页面做落地页

普通内容页加两行 front matter 即成为落地页：全宽画布，保留顶栏、命令面板与页脚，去掉侧栏与目录。

---
title: 价格
layout: landing
landing: pricing
---

数据放在与首页平行的目录下，同样按语言分文件：

非首页落地页按这个顺序查找数据。全部找不到时，普通预览告警并渲染没有分区的 Landing 外壳；严格发布构建拒绝这条警告：

1. 页面 front matter 里的 sections；
2. data/landing/<key>/<精确语言>.yaml；
3. 单文件 data/landing/<key>.yaml 里的精确语言条目；
4. 英文或无语言后缀的记录。

数据量小时可以写在 front matter 里，但 landing: 与 sections: 互斥：

---
title: 价格
layout: landing
sections:
  - type: hero
    data:
      title: 只用 Hugo 发布产品页面
      actions:
        - { label: 阅读文档, url: docs/, style: primary }
  - type: download
    data: { title: 下载, keys: [prd5] }
  - cta
---

分区条目写法

sections 的每一项可以是一个类型名字符串，也可以是一个 Map：

多语言与本地事实

叙事文字优先分语言文件（zh.yaml / en.yaml）。共享的事实记录也可以在字段级回退：<字段>_<精确语言> → <字段>_<主语言> → <字段>，语言标签里的 - 规范化成 _。中文站解析 title_zh_cn、title_zh、title。不接受 camelCase 后缀。

分区里的显示文字是站点数据，不是主题的 i18n 字符串。只有跑马灯暂停、定价状态这类主题自带控件用翻译键。多语言站点的整体配置见多语言。

落地页外壳上的几个可选事实也是本地的，写在 hugo.yml 里，运行时不会去取它们：

params:
  offline_search: true
  ui:
    landing_search: true          # 布尔；只有站点开了 offline_search 才显示命令面板
    github_stars: 2189            # 已提交的数字，不请求 GitHub API
    alt_site: { label: English site, url: 'https://example.com/' }

页脚不属于首页数据：它读 data/footer/<语言>.yaml（单语言站点用 data/footer.yaml），本站两种语言各一份。data/home/<语言>.yaml 里残留的 footer 键会在普通预览中告警并忽略，--panicOnWarning 会拒绝它并提示新位置。 写法见导航与菜单。

输出形态

禁用 JavaScript 后服务端文档仍然完整。跑马灯的副本轨道不进无障碍树，暂停用的是不依赖 JavaScript 的复选框；读者开启减少动态效果偏好时，移动与渐显关闭。

验证

1. 构建零告警：hugo --printPathWarnings --panicOnWarning。类型写错、数据键不存在、landing 与 sections 同时出现都在这一步暴露。
2. 打开首页与落地页，逐个分区对照数据文件，每种语言各看一遍。
3. 禁用 JavaScript 后刷新：内容仍在，只是没有动效。
4. 深浅色各看一遍，确认 image.light / image.dark 都给对。
5. 部署到子路径时，确认站内链接与图片都带上了前缀。

相关

• 品牌外观 — 站名、Logo、配色与字体
• 导航与菜单 — 顶栏、页脚与语言菜单
• 发布与下载页 — download 分区的数据来源
• 多语言 — 语言启用与数据分文件
• 配置总览 — params.ui.landing_search 等参数的完整定义

4 - 导航与菜单

本页覆盖读者在页面之间移动的入口：顶栏菜单、栏目切换器、面包屑、页面操作、上一页 / 下一页与页脚。侧栏树与目录属于布局与页面类型。

导航没有第二套信息架构：顶栏来自 Hugo 的 menus.main，侧栏来自 content/ 的目录结构。主题不读 docs.json、navigation.yaml 一类的并行导航树。

顶栏菜单

顶层入口写在各语言的 menus.main 里：

languages:
  zh:
    menus:
      main:
        - identifier: docs
          name: 文档
          pageRef: /docs
          weight: 20
        - identifier: blog
          name: 博客
          pageRef: /blog
          weight: 50
        - identifier: download
          name: 下载
          pageRef: /download
          weight: 60
          params:
            icon: fa-solid fa-download

weight 越小越靠前。pageRef 指向站内页面，url 指向外链；外链自动加 target="_blank" 与 rel="noopener noreferrer"，并带一个外链角标。identifier 是配置里引用这个入口的稳定标识（quick_links、sidebar_root_menu 按它匹配），name 按语言翻译，identifier 不翻译。

菜单项也可以挂在页面 front matter 上，适用于「这一页本身就是一个顶层入口」：

---
title: 下载
menu:
  main:
    weight: 30
---

顶栏右侧的 GitHub 入口 不是 菜单项，它来自 params.github_project_repo（未设时回落 params.github_repo）。标识为 github 的菜单项会被菜单区跳过，写了也不显示。改变这个入口的目标要改仓库参数，见仓库与页面信息。

下拉菜单

用 Hugo 的 parent 建立父子关系，只支持一级子项：

menus:
  main:
    - identifier: docs
      name: 文档
      pageRef: /docs
      weight: 20
    - identifier: docs-start
      parent: docs
      name: 快速上手
      pageRef: /docs/start
      weight: 10
      params:
        icon: fa-solid fa-rocket
        description: 从 OINK Starter 起步，分层定制并部署
    - identifier: docs-components
      parent: docs
      name: 组件
      pageRef: /docs/components
      weight: 20
      params:
        icon: fa-solid fa-cubes

• 每个条目都是独占一行的一个图标加一个标题，整个面板是一列宽度适中的 纵向列表。子项的 params.description 只是配置数据，面板不会渲染它。
• 父级本身是一个普通链接：悬停或键盘聚焦展开面板，点击或回车进入父级页面。没有单独的展开箭头，触屏读者落到父级页面，该页正文同样列出这些链接。
• 键盘：向下箭头展开并聚焦第一项，Esc 关闭并把焦点还给链接，点击面板外部关闭。
• 0.5 的 params.columns 参数已退役：设置它会发出构建警告，面板保持单列。
• 再深一层会发出构建警告并降级成静态分组标题，不会 生成三级悬浮菜单。更深的层级放进侧栏。

菜单图标

小于 lg 时菜单项只剩图标，每个顶层入口都应有一个。图标按这个顺序解析：

1. 目标页面 front matter 里的 icon；
2. 菜单项自己的 params.icon；
3. 按 identifier / 分区名匹配的内置默认值（docs blog examples community about download github 等）；
4. 都没有时用 fa-solid fa-link。

图标写成一对 Font Awesome class，主题本地提供免费版字体：

menus:
  main:
    - identifier: handbook
      name: 运维手册
      pageRef: /handbook
      weight: 40
      params:
        icon: fa-solid fa-screwdriver-wrench

标签菜单

顶层入口指向 taxonomy 页面（/tags/、/categories/）时不需要手工配置子菜单：面板自动渲染「标签 + 数量」的 chip 网格，按数量降序排列。

menus:
  main:
    - identifier: tags
      name: 标签
      pageRef: /tags
      weight: 60

分类怎么启用见分类体系。

顶栏控件

顶栏高 50px，从左到右是：品牌（Logo 或字标）、菜单区、搜索、版本、语言、主题、GitHub。首页和 Landing 页面最右侧还固定保留抽屉菜单按钮。顶栏在所有布局上渲染；文档、博客和分类页使用相同控件，但没有这个 Landing 抽屉。

顶栏分为桌面完整形态与紧凑图标形态：

各控件的开关不在这里：搜索图标要 params.offline_search（见全文检索），版本菜单要 params.versions（见多版本），语言菜单在配置了两种及以上语言时自动出现（见多语言），主题控件要 params.ui.dark_mode（见品牌外观）。

自动隐藏

params:
  ui:
    navbar_autohide: true

开启后顶栏离开正常流、停在视口上方，指针进入原位置上方 60% 的中间区域（或键盘焦点进入）才滑出，并且覆盖在正文之上，不把正文顶下去。左右各 64px 不属于唤醒区，避免盖住折叠后的侧栏与大纲恢复按钮。

小于 768px、粗指针或纯触屏时自动停用，顶栏始终可见。页面 front matter 顶层的 navbar_autohide 或分区 cascade 可以逐段覆盖。

关闭顶栏

params:
  ui:
    navbar_enabled: false

也可以只关闭某一页或某一段：

---
title: 文档
cascade:
  navbar_enabled: false
---

关闭后主题补回原本由顶栏承担的界面：移动端子导航、侧栏顶部的品牌与搜索行、大纲轨道上的工具按钮。这个开关适用于必须独占视口的页面，不作为常规排版偏好。本站的文档栏目使用它：文档页依靠侧栏导航，顶栏是多余的一行。

栏目切换器

侧栏顶部那一行是栏目切换器，决定当前显示哪棵树。入口集合按顺序去重构造：所有顶级栏目 → 全站所有 sidebar_root_for: self 的分区 → 当前解析出的根。

params:
  ui:
    sidebar_root_enabled: true
    sidebar_root_menu: true

让一棵大子树自成一个根（带版本的 API 参考、独立手册），在它的 _index.md 里：

---
title: API 参考 v2
sidebar_root_for: self
sidebar_root_link_self: true
---

self 让这个分区索引与它的后代都用这棵新树；children 把索引留在父树里，只约束后代。让某个顶层分区不出现在切换器里，在它的 front matter 里设 sidebar_root_menu: false。

只有一个入口时切换器退化成一个无边框链接，两个及以上才是下拉菜单。切换器下面的树仍然把栏目首页本身作为第一个链接：切换器选一棵树，根链接选一篇文档。

面包屑与页面操作

普通内容页标题上方是面包屑行，这一行右端同时承载页面操作。顶层分区省略只有一级、与标题重复的面包屑，操作按钮的位置不变。

params:
  ui:
    breadcrumb: false

面包屑标签取本地化的 linkTitle，层级与侧栏一致。

页面操作菜单

页面操作是标题行末尾的拆分按钮：左半边一键复制本页 Markdown（成功后变成绿色对勾），右侧箭头展开完整菜单。菜单分两组，上半组是取走内容，下半组是改动与产出：

params:
  ui:
    page_context_menu:
      enable: true
      assistant_links: false
      links: []

助手入口默认关闭：读者点击时，完整的当前 URL（含 query 与 fragment）会随本地化提示词发给第三方，页面正文不上传。开启前确认 URL 里没有敏感信息，并在隐私说明里披露这个边界。页面可以用布尔型 front matter assistant_links 收紧站点策略，不能反过来替站点开启。

自定义外部操作排在菜单最后，url 支持三个已 URL 编码的占位符：

params:
  ui:
    page_context_menu:
      links:
        - name: 询问内部助手
          icon: fa-solid fa-wand-magic-sparkles
          url: https://assistant.example.com/new?source={markdown_url}&title={title}

可用占位符：{url}（页面完整地址）、{title}（页面标题）、{markdown_url}（Markdown 版地址）。

在博客根分区及其一级子分区上，左半边变成 RSS 订阅链接，菜单里仍保留「复制 Markdown 文本」。没有 Markdown 输出的页面去掉左半边，箭头变成带文字的「操作」按钮。

这些操作同时是命令面板里的条目。

翻页器

正文末尾的上一页 / 下一页是两个文本链接，顺序与侧栏可见树一致：根页 → 第一篇 → 直到最后一篇。根页没有上一页，末页没有下一页。站点提供 data/docs_nav.json 时，这棵显式树同时决定翻页顺序，以及该文件声明过的 docs / book 栏目的栏目索引顺序——侧栏、翻页器与索引不会再把同一批子页排出三种顺序。文件没有声明的栏目，以及没有这个文件的站点，仍然沿内容树走。见布局与页面类型。

params:
  ui:
    pager_types: [docs, book, blog]

pager_types 只接受 docs、book、blog 三个值，其它取值告警并丢弃。单页退出用 front matter：

---
title: 附录
pager: false
---

同一份顺序也写进 <head>：有上一页 / 下一页时输出 <link rel="prev"> 与 <link rel="next">，供浏览器与爬虫识别阅读序列。

<link rel="prev" href="/zh/docs/customize/home/">
<link rel="next" href="/zh/docs/customize/layout/">

翻页只在 HTML 输出中生效。打印、Markdown 与 RSS 既没有翻页链接，也没有这两个 rel 关系。

翻页器是页尾四件套的第三件（反馈 → 页面信息 → 翻页 → 评论），顺序固定，四者独立开关。

反向链接

右栏可以列出有哪些页面链接到这一页：一个带链接图标的「反链」组，排在目录下方、分类标签云上方，默认展开；低于 xl 断点时，它随目录一起进入侧栏抽屉。从搜索落到这一页的读者由此看到哪些页面认为它值得指向，也看到它在站点其余部分里的位置。默认关闭，由站点打开：

params:
  ui:
    backlinks: true

单页用 front matter 覆盖，分区用 cascade 覆盖它下面的所有页面：

---
title: 文档
cascade:
  backlinks: true
---

索引在构建时从作者本来就在写的东西里派生：页面源码里的普通 Markdown 链接，以及 ref / relref shortcode。没有新语法要学，没有内容要迁移，也不需要 JavaScript——列表就在 HTML 里。扫描前先剥掉代码围栏与行内代码；指向同一个目标的多个链接合并成一条；自链接、外链、mailto: 与同页锚点都不计入。判断目标页面时去掉 fragment，每种语言各有一张互不相干的图，中文页面不会出现在英文页面下面。条目按稳定页面路径排序，同样的内容每次构建出同样的顺序；没有任何页面链进来时整个区块不渲染——没有标题，也没有空容器。

前八条直接可见，其余折进原生的「再显示 N 条」disclosure，避免被大量引用的页面把右栏撑满，其中不涉及 JavaScript。每一条都带来源页面的描述，悬停时显示。

读源码有一处已知遗漏：写在自定义 shortcode 参数里或原始 <a href> 里的 URL 不会成为一条边；解析不出来的目标被静默丢弃，不发告警。它是导航增强，不是链接检查器，查断链仍然要用链接检查器。

非布尔取值告警并回落到关闭，hugo server 照常可用，加了 --panicOnWarning 的构建会停在这里。

页面的 Markdown 输出带同一份列表，前缀是「反链：」。RSS 省略它，print 输出格式连同整个右栏一起省略。

本站全站开启了它：看本页右栏的「反链」组就是实际效果；被引用最多的配置总览一页，列出了四十多个入链，其中大部分收在「再显示 N 条」里。

页脚

页脚形态由 params.ui.footer_style 决定（fat / slim / none，见品牌外观）。fat 的多列链接网格读 data/footer/<语言>.yaml。它不是菜单，主题没有 menus.footer：

brand:
  name: 产品文档
  tagline: 一段简短的**支持 Markdown 的**说明。
  slogan: 贴近产品，给出明确答案。
columns:
  - title: 文档
    links:
      - { label: 快速上手, url: /zh/docs/start/ }
      - { label: 组件, url: /zh/docs/components/ }
  - title: 项目
    links:
      - { label: GitHub, url: https://github.com/pgsty/oink, external: true }
      - { label: 发布记录, url: /zh/blog/release/ }

• brand.name 与 brand.logo 不写时回落到站点自己的品牌名、Logo 与字标；tagline 与 slogan 渲染 Markdown。
• 站内 url 相对当前语言根解析；external: true 在新标签页打开并带 rel="noopener noreferrer"。
• 网格列数等于数据里的列数。
• 单语言站可以使用 data/footer.yaml。
• 配了 fat 但没有数据时自动降级成 slim，可以先开启再补内容。

fat 页脚的版权行右端有一个折叠箭头，收起或恢复它上方的链接栅格。默认展开，读者的选择存在 localStorage 的 td-footer-collapsed 键里，跨页面保留；slim 与 none 没有这个按钮，它也与专注模式无关。

只要页脚有渲染，最底层栏右侧就固定保留同一组图标：版本、语言、主题、快捷键帮助。各菜单向上展开；版本按钮只显示分支图标，完整版本名仍保留在选项中。fat 页脚的折叠箭头排在这四项之后。侧栏不再重复这组控件，footer_style: none 则连同页脚一起移除底栏。

版权行与中间那句说明由参数控制，见配置总览。

验证

hugo --printPathWarnings --panicOnWarning

改完导航要检查这几处：

• 构建没有 Navbar menu … supports one interactive child level 警告；出现它说明菜单嵌了三层；
• 桌面端：父级菜单点击进入父级页面，悬停展开面板，Esc 关闭面板；
• 窗口缩到 lg 以下：每个顶层入口仍有图标，没有图标的项在这个宽度下是空白；
• 缩到 md 以下：首页与 Landing 顶栏右侧只剩搜索和抽屉按钮；版本、语言、主题与快捷键帮助固定在 footer 最底层栏；
• 侧栏顶部的切换器列出所有顶级栏目，当前项有选中标记；
• 任意文档页按 E / Q 翻页，顺序与侧栏一致，页面源码里有对应的 rel="prev" / rel="next"；
• 打开反向链接后，grep td-backlinks public/<某个被链接的页面>/index.html 能找到这个区块，而没有页面链进来的页面里完全没有这段标记；
• 打开页面操作菜单，确认该出现的项都在，不该出现的没有（例如未配置 github_project_repo 时的「提交项目 issue」）。

相关

• 布局与页面类型 — 侧栏树、目录与外壳类型
• 配置总览 — 导航相关参数的默认值
• 命令面板 — 页面操作与自定义命令
• 仓库与页面信息 — 编辑本页、历史与 issue 链接
• 组织内容 — 目录结构如何决定侧栏

5 - 布局与页面类型

本页覆盖页面骨架：有没有侧栏、侧栏多宽、目录收几级、栏目首页是列表还是卡片。内容放在哪个目录见组织内容，这里只讲外壳。

规则是 外壳看 type，不看路径。文档可以放在 content/ 下的任何位置，只要给它 type: docs。

外壳类型

params.ui.shell_types 列出哪些 type 使用带侧栏的阅读外壳：

params:
  ui:
    shell_types: [docs, book, blog, swagger]

分类页与标签页（taxonomy / term）不在这张表里，但也走同一套外壳。

给一棵子树指定 type 用 cascade，这是把文档放在任意路径的做法：

---
title: 运维手册
type: docs
cascade:
  type: docs
---

栏目根只是导航起点

params:
  ui:
    docs_section: docs
    blog_section: blog

这两个键 不决定外壳，只告诉主题文档树与博客树的根在哪，用于解析侧栏根、快捷入口与默认图标。上面 content/handbook/ 的例子照样有文档外壳，docs_section 保持 docs 不影响它。

需要让 docs 页的侧栏根变成站点首页，而不是文档栏目时：

params:
  ui:
    docs_sidebar_root: home # home | section

取值只有这两个。其它值在普通预览中告警并使用 section，严格发布构建通过 --panicOnWarning 拒绝这条警告。

文档挂在站点根

以文档为主的站点可以把 docs 分区发布到 URL 根路径，源码仍然放在 content/docs/ 下。这需要三段配置一起给出。

第一段用 Hugo 原生的 permalinks 去掉 URL 里的 docs/ 段：

permalinks:
  page:
    docs: /:sections[1:]/:slug/
  section:
    docs: /:sections[1:]

第二段让物理站点根索引仍可作为链接目标，但不再争抢同一个输出路径。每种语言的站点根索引（content/_index.md、content/_index.zh.md）都要写：

---
title: 产品文档
build: { render: link }
---

第三段把侧栏根声明为站点首页，让侧栏与翻页共用同一棵树：

params:
  ui:
    sidebar_root_enabled: true
    docs_sidebar_root: home

docs_sidebar_root: home 之后，站点首页的所有顶层分区都会进入这棵树。博客、社区、下载这类不属于阅读序列的概览分区，在自己的 _index.md 里设 toc_root: true 退出，它们既不出现在树里，也不成为翻页目标：

---
title: 博客
toc_root: true
---

文档此时与博客、社区等分区共享 URL 根路径。构建加 --printPathWarnings，发布前解决所有重复目标。

落地页

任意页面加 layout: landing 即使用落地页布局：顶栏 + 分区拼装的正文 + 页脚，没有侧栏。数据写法见首页与落地页。

params:
  ui:
    landing_search: true

landing_search: false 会把搜索入口从落地页外壳里去掉，其它页面不受影响。

侧栏

侧栏树来自 content/ 的目录结构，按 weight 排序，有 linkTitle 时用它作为标签。可调的是密度与尺寸：

params:
  ui:
    sidebar_menu_compact: true
    sidebar_menu_foldable: true
    sidebar_menu_truncate: 2000
    sidebar_width_min: 220
    sidebar_width_max: 480
    sidebar_item_overflow: ellipsis # ellipsis | wrap
    sidebar_expand_levels: 2

• sidebar_menu_compact 只展开当前分支及邻近条目；设为 false 时整棵树全展开。
• sidebar_menu_foldable 允许读者手动展开 / 折叠分区。博客栏目默认展开；某个分区要默认收起，在它的 _index.md 里写 sidebar_expanded: false。
• sidebar_expand_levels 是默认展开的层级数。
• sidebar_menu_truncate 是单个分区最多渲染的条目数，避免上千页的目录把 HTML 撑到不可用。
• sidebar_width_min / sidebar_width_max 是桌面端拖拽调宽的上下限（像素）。读者调整后的宽度存在浏览器本地，双击分隔条恢复默认。
• sidebar_item_overflow 默认 ellipsis（长标题省略），中文长标题多的站点可以改 wrap 换行。

折叠状态、宽度与滚动位置保存在读者本地，按语言隔离。小于 md 时侧栏变成带遮罩的抽屉。

单页去掉侧栏用 front matter：

---
title: 全屏报告
sidebar_enabled: false
---

显式导航树 data/docs_nav.json

侧栏树默认从 content/ 推导。站点也可以给出一份显式导航清单，三个条件同时成立时主题改用它渲染：

• 站点存在 data/docs_nav.json 且其中有 sections 键；
• 页面的 type 是 docs 或 book；
• 解析出的侧栏根不是站点首页。

文件是一棵嵌套的节点树。每个节点用 page 指向内容路径，url 是它的链接，children 是子节点；active_path_by_url 记录每个 URL 对应的祖先链，供当前项高亮使用：

{
  "sections": [
    {
      "page": "/docs/start",
      "url": "/docs/start/",
      "children": [{ "page": "/docs/start/install", "url": "/docs/start/install/" }]
    }
  ],
  "active_path_by_url": {
    "/docs/start/install/": ["/docs/start/"]
  }
}

URL 在比较前去掉语言前缀，一份文件服务所有语言。

这棵树同时决定翻页顺序，侧栏与上一页 / 下一页不会出现两种排序。sections 为空数组 时告警并回退到内容树；page 指向不存在的页面时告警并跳过该项。严格发布构建拒绝 任一警告。带 manual_link 的占位节点与 sidebar_divider 分隔行留在侧栏里，但不会 成为翻页目标。

适用场景是导航顺序由外部工具生成的站点，例如从 Sphinx toctree 迁移过来、需要冻结既有章节顺序的手册。顺序由 content/ 的 weight 维护时不需要这个文件。

侧栏图标密度

页面 front matter 里的 icon 会出现在侧栏。叶子页全部带图标会降低可读性，用密度策略控制：

params:
  ui:
    sidebar_icon_policy: groups # all | groups | none

非法取值只发警告并回落到 all，不让构建失败。本站使用 groups。

在侧栏里展开标题

Book 页可以在侧栏当前行下展开 h2–h4 分支，便于在长章节内跳转：

params:
  ui:
    sidebar_headings: 3 # false | true | 2 | 3 | 4

整数指定展开到第几级（2–4），true 等于 2（只展开 h2），false 关闭。取值超出 范围时普通预览告警并关闭标题分支，严格发布构建拒绝这条警告。只对 type: book 的页面生效，且只在侧栏当前行下展开。

目录 TOC

右栏大纲由 Hugo 从 Markdown 标题生成，收录层级是 Hugo 原生配置：

markup:
  tableOfContents:
    startLevel: 2
    endLevel: 4
    ordered: false

主题只管跟踪行为：

params:
  ui:
    scroll_spy: false