diff --git a/docs/javascripts/toc-collapse.js b/docs/javascripts/toc-collapse.js
index e04bf49a5..20d3f6a5c 100644
--- a/docs/javascripts/toc-collapse.js
+++ b/docs/javascripts/toc-collapse.js
@@ -74,15 +74,19 @@
userPinned.clear();
autoExpanded.clear();
- // Mark all nav roots so CSS can scope styles
- sidebar.querySelectorAll("nav.md-nav").forEach(function (nav) {
- nav.classList.add("md-nav--integrated");
- });
-
- // Find every
inside the actual TOC (md-nav--secondary) that has
- // nested children. We scope to the secondary nav to avoid touching the
- // page-level nav item that wraps the TOC — that item contains a
- // for the mobile TOC toggle and would show up as a bogus duplicate entry.
+ // Find the actual TOC (md-nav--secondary). We scope to the secondary
+ // nav to avoid touching the page-level nav items that wrap sections —
+ // those use Material's native checkbox-based toggle and should not be
+ // overridden.
+ //
+ // NOTE: The primary nav already has .md-nav--integrated added by
+ // mkdocs-material when the toc.integrate feature is enabled. We do
+ // NOT re-add that class or extend it to descendant navs — doing so
+ // causes the CSS rule ".md-nav--integrated .md-nav__item--nested >
+ // .md-nav { display: block }" to override Material's native
+ // checkbox-based collapse on primary nav sections (Reference,
+ // Development, Architecture Decisions, etc.), creating whitespace
+ // below collapsed section headings.
var tocNav = sidebar.querySelector("nav.md-nav--secondary");
if (!tocNav) return;
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 83fb9d0b9..0cb84594e 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -98,10 +98,57 @@
min-width: 0;
}
+/* --- Primary nav section collapse fix -----------------------------------------
+ *
+ * Material's native checkbox-based toggle for nav sections (Reference,
+ * Development, Architecture Decisions, etc.) must fully hide children
+ * when unchecked. Without this, the container retains residual
+ * height from padding/grid-rows even when the checkbox is unchecked,
+ * causing visible whitespace below collapsed section headings.
+ * ----------------------------------------------------------------------- */
+
+/* Fully hide children of unchecked primary nav sections */
+.md-sidebar--primary .md-nav__item--nested > .md-nav__toggle:not(:checked) ~ .md-nav {
+ display: none;
+}
+
+/* --- Active page TOC collapsibility -------------------------------------------
+ *
+ * With toc.integrate, Material shows the page's TOC in the left sidebar
+ * but hides the toggle on desktop (>= 76.25em), making the TOC
+ * always visible with no way to collapse it. These rules show the toggle
+ * label (with its chevron icon) at all screen sizes, hide the duplicate
+ * link, and respect the __toc checkbox for collapse/expand.
+ * ----------------------------------------------------------------------- */
+
+/* Show the TOC toggle label on desktop so users can collapse the TOC */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > label.md-nav__link[for="__toc"] {
+ display: flex !important;
+}
+
+/* Activate the chevron icon inside the label */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > label.md-nav__link[for="__toc"] .md-icon::after {
+ content: "";
+}
+
+/* Hide the duplicate navigation link (user is already on this page) */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > label.md-nav__link[for="__toc"] + .md-nav__link {
+ display: none;
+}
+
+/* When the TOC checkbox is unchecked, hide the TOC.
+ * This overrides Material's "display: block" rule that forces the TOC
+ * visible for the active page. */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > #__toc:not(:checked) ~ .md-nav--secondary {
+ display: none !important;
+}
+
/* --- Collapsible TOC in integrated sidebar --- */
-/* Container for the link row: link text + toggle chevron side by side */
-.md-nav--integrated .md-nav__item--nested > .md-nav__link {
+/* Container for the link row: link text + toggle chevron side by side.
+ * Scoped to .md-nav--secondary (the TOC) so it does not affect primary
+ * nav section headings which use Material's native + checkbox. */
+.md-nav--secondary .md-nav__item--nested > .md-nav__link {
display: flex;
align-items: center;
}
@@ -144,13 +191,13 @@
transform: rotate(-90deg);
}
-/* Hide nested nav list when collapsed */
-.md-nav--integrated .md-nav__item--nested.toc-collapsed > .md-nav {
+/* Hide nested nav list when collapsed (TOC items only) */
+.md-nav--secondary .md-nav__item--nested.toc-collapsed > .md-nav {
display: none;
}
-/* Show nested nav when expanded */
-.md-nav--integrated .md-nav__item--nested > .md-nav {
+/* Show nested nav when expanded (TOC items only) */
+.md-nav--secondary .md-nav__item--nested > .md-nav {
display: block;
}