组织内容

OINK 不需要单独配置导航：content/ 下的目录结构就是侧栏树。本页覆盖目录与文件的摆放、栏目首页、排序、图标、折叠、隐藏，以及多根侧栏。

目录就是侧栏

一个目录是一个栏目（Hugo 称 section），目录里的 Markdown 文件是它的页面，嵌套目录是它的子栏目。侧栏按这棵树逐层渲染，顺序由 weight 决定，标签取 linkTitle，缺省时取 title。左侧这棵树的源码如下：

每个目录都要有 _index.md

栏目首页是目录里的 _index.md（中文为 _index.zh.md）。缺少它时 Hugo 仍会生成栏目，但没有标题、描述、图标与 weight：侧栏那一行显示目录名，排序不受控制。

---
title: 部署上线
linkTitle: 部署
description: 把站点发布到 GitHub Pages、Cloudflare Pages 或自己的 Nginx。
weight: 50
icon: fa-solid fa-cloud-arrow-up
---

栏目 _index.md 另有一项专属能力：用 cascade 把共享设置一次下推给整棵子树，不必每页重复。

---
title: 参考
weight: 90
cascade:
  pager: false        # 这个子树里的页面都不显示上一页 / 下一页
  search_boost: 0.8   # 参考页在搜索里排后一点
---

排序：weight 用 10 的倍数

同一栏目里的页面按 weight 升序排列，weight 相同时才退回日期与 linkTitle 字母序。一律用 10 的倍数（10、20、30），此后往中间插页不必改动其它页。栏目自身的 weight 决定它在父级里的位置。

没写 weight 的页面视为 0，Hugo 把它们排在所有写了 weight 的页面之后，彼此按日期与标题排列。这个顺序会随内容改动漂移，因此每页都写上 weight。

单文件还是页面包

没有自身资源的页面用单文件 slug.md；带图片、cast、示例文件的页面改成目录加 index.md，资源与它同放。两种形态在侧栏里没有区别，URL 也相同。详见编写页面。

栏目首页显示子页列表还是卡片

_index.md 的正文之后，主题自动接上子页索引，两种样式：

params:
  ui:
    section_index: cards # list | cards

list 是主题默认，每个子页一行标题加描述；cards 是链接卡片网格，读取子页的 icon、linkTitle 与 description。本站用 cards，本栏目首页即是例子。单个栏目需要另一种样式时在它的 front matter 里覆盖：

section_index: list
cascade:
  section_index: list   # 连同后代栏目一起

两个页面级开关不受样式影响：simple_list: true 渲染紧凑的项目符号列表，no_list: true 不生成索引，用于正文自行手写导航的场合。

侧栏图标

在页面或栏目的 front matter 里写一对 Font Awesome class：

icon: fa-solid fa-cloud-arrow-up

图标密度是站点级策略，用于避免叶子页全部带图标：

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

新站点建议显式写 groups：保留分组的语义标识，去掉叶子层的图标。本站使用这个设置，左侧只有六个栏目带图标。

展开与折叠

有子页的栏目在侧栏里带一个折叠箭头，读者的展开状态保存在本地。默认行为：当前页所在的那条路径展开，其余收起；博客类栏目默认展开。

sidebar_expanded: true   # 这个栏目始终默认展开

站点级的折叠、紧凑模式、初始展开层数、宽度与截断在布局与页面类型里配；键的完整定义见配置总览。

从侧栏里藏起来

toc_hide 与 hide_summary 控制两个不同的入口，两处都不该出现时才同时设置。

外壳由 type 决定，不是路径

文档外壳（侧栏、目录、面包屑、翻页器）不取决于目录名，只取决于页面的 type 是否在 params.ui.shell_types 里：

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

文档因此可以放在任意路径，用 cascade 指定 type 即可。例如把一套手册放在 content/handbook/，栏目根的写法如下：

---
title: 运维手册
type: docs
sidebar_root_for: self      # 侧栏树的根即本栏目，不回退到 /docs
cascade:
  type: docs                # 整棵子树都用文档外壳
---

多根侧栏

侧栏树默认以读者所在的顶层栏目为根，树上方一行标出当前的根。规模较大的子树可以自己成为一个根，例如带版本的 API 参考或一本独立的手册：

---
title: API 参考 v2
sidebar_root_for: self   # self | children
---

根节点上方的切换器是全站的：它列出所有顶层栏目，加上站内所有 sidebar_root_for: self 的栏目。只有一个入口时它退化成一个普通链接，两个及以上才是下拉菜单。顶层栏目不出现在切换器里时，在它的 _index.md 写 sidebar_root_menu: false。

切换器下方，栏目首页仍是树里的第一个链接：切换器选择一棵树，根链接指向一篇文档。sidebar_root_link_self: false 让根那一行改为指向父级栏目。

验证

hugo --printPathWarnings --panicOnWarning

必须 Total in …，没有 ERROR / WARN。--printPathWarnings 报出两个页面指向同一输出路径的情况，改目录结构时较常出现。

在浏览器里逐项确认：

1. 侧栏里的顺序与写下的 weight 一致，新栏目出现在预期位置；
2. 栏目首页的子页索引齐全（缺项来自 hide_summary 或缺少 _index.zh.md）；
3. 面包屑与翻页器的顺序与侧栏一致，翻页器读的是同一棵树；
4. 换语言之后树的形状相同（每个 _index.md 都要有 .zh.md 对等文件）。

侧栏条目超过 params.ui.sidebar_menu_truncate 时构建给出警告，并指出应调到多少。这个警告不可忽略：被截断的条目不会出现在侧栏里。

相关

• 编写页面 — 单页怎么写
• 页面参数 — 这页出现的每个 front matter 键的完整定义
• 布局与页面类型 — 站点级的外壳、侧栏与目录设置
• 导航与菜单 — 顶栏菜单、面包屑与翻页器
• 多语言 — 双语目录树怎么保持一致