让侧栏所有分组都能折叠(关掉 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;
}
但这治标不治本,原因有二:
- 箭头对应的
<label>在开着sections时根本没生成(见上节),没有元素可显示。 - 就算有元素,Material 9.7.6 里
--section相关的 CSS 也只是给箭头改个颜色(color: var(--md-default-fg-color--light)),并不是display:none把它藏起来——所以「用 CSS 覆盖 display」这个思路从前提上就站不住脚。
结论:纯 CSS 救不了语义层面没有的折叠开关。
正解:关掉 navigation.sections¶
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 时建议把两笔合并。)