跳转至

让侧栏所有分组都能折叠(关掉 navigation.sections)

一句话结论:MkDocs Material 的 navigation.sections 这个 feature 本身就会把导航分组变成「不可折叠的常开头」;想要每个分组都能点箭头收起,直接把它从 theme.features 里关掉就行。

问题:侧栏分组点不开

站点左侧导航里,像「嵌硬 · 硬件与半导体」「工作与项目 / AHRS 板固件仿真与验证」这类分组,没有折叠三角、点了也不收起——整组一直摊开占着屏幕。

根因:不是 CSS 藏了箭头,是 DOM 里压根没开关

navigation.sections 的语义是「把每个导航分区渲染成一个分区头(section header)」。在这种模式下,分区对应的 <li> 会被加上 md-nav__item--section 类,而 Material 压根不为它生成折叠用的 <input type="checkbox"> 和 <label> 开关——也就是说,从 HTML 结构层面就不存在「收起」这件事,不是被 CSS 藏起来的。

对比一下两种模式生成的同一个分组:

  • 开着 sections:<li class="… md-nav__item--section …"> —— 只有标题,没有折叠开关。
  • 关掉 sections:<li class="md-nav__item md-nav__item--nested"> 里带着 <input type="checkbox" id="__nav_x"> 和 <label for="__nav_x"> —— 这就是标准的可折叠嵌套项。

所以「没三角、点不动」是 feature 的本来设计,不是 bug。

走过的弯路:只靠 CSS 强行显示箭头

第一版尝试写了一段 extra_css,想用后代选择器把「分区头的折叠箭头」强行显示出来:

.md-nav__item--section .md-nav__link[for] {
  display: inline-flex;
  pointer-events: auto;
  cursor: pointer;
}

但这治标不治本,原因有二:

  1. 箭头对应的 <label> 在开着 sections 时根本没生成(见上节),没有元素可显示。
  2. 就算有元素,Material 9.7.6 里 --section 相关的 CSS 也只是给箭头改个颜色(color: var(--md-default-fg-color--light)),并不是 display:none 把它藏起来——所以「用 CSS 覆盖 display」这个思路从前提上就站不住脚。

结论:纯 CSS 救不了语义层面没有的折叠开关。

mkdocs.yml 的 theme.features 里删掉这一行即可:

features:
  - navigation.tabs          # 顶部标签导航(参考项目风格,更简洁)
  - navigation.indexes       # 分区标题有专属首页(index.md),点击分区名可进入
  # - navigation.sections   # ← 删掉这行:它让分组变成不可折叠的常开头
  - navigation.footer
  - navigation.top
  - navigation.tracking
  - toc.follow
  - content.code.copy
  - search.suggest
  - search.highlight

关掉之后,所有分组自动变回 md-nav__item--nested,自带 checkbox + label 折叠开关,全部可折叠。

代价:关掉 sections 后,分组标题失去了原生加粗的观感。用一小段 CSS 还原,顺便加一道 !important 安全网(防止任何版本把 --section 的箭头藏掉):

/* docs/stylesheets/nav-section-collapse.css */
/* 1) 强制「当前所在分组」的折叠箭头可见、可点击 */
.md-nav__item--section .md-nav__link[for],
.md-nav__item--section > .md-nav__link > [for] {
  display: inline-flex !important;
  pointer-events: auto !important;
  cursor: pointer;
}
/* 2) 关掉 sections 后还原分组标题加粗 */
.md-nav__item--nested > .md-nav__link,
.md-nav__item--section > .md-nav__link {
  font-weight: 700;
}

这段 CSS 走的是 extra_css,和站点原本的 stylesheets/extra.css 一并被复制到 site/stylesheets/ 下、正常进 <head>。

验证:解析构建产物,数「折叠开关」

没靠截图,而是直接扒构建出来的 HTML,统计每个带子项的导航 <li> 是否同时具备「勾选框 id」和「指向同一 id 的 label」:

  • 首页导航里共 14 个父分组;
  • 14/14 都成对具备 checkbox id == label for,0 缺失、0 错配;
  • 重点点名的两个——AHRS 板固件仿真与验证、嵌硬 · 硬件与半导体——实测均为 --nested 且可折叠。

构建本身 EXIT=0、0 ERROR(那 65 条 WARNING 是惯性导航重组进行中、尚未提交的 nav 条目导致的,与本次无关)。

顺带清理

mkdocs.yml 里曾经出现两处 extra_css: 键(YAML 重复键)。实测重复键在本项目无害(extra_css 会复制到 site/stylesheets/,两个 CSS 都正常进 <head>),但为整洁还是删掉了误建的那处,只留合并后的列表。

提交

  • 提交 cdbb05a:仅 mkdocs.yml + docs/stylesheets/nav-section-collapse.css 两个文件。
  • 工作区里惯性导航重组等 76 处未提交改动全程未触碰(已确认 git diff HEAD 只含这两文件)。
  • 沙箱推不上去,需在桌面 git push origin main。(308a73e 已被本次提交实质取代,push 时建议把两笔合并。)