From 557d39332c7909ccb86493f836b6f1c5dccd54d1 Mon Sep 17 00:00:00 2001
From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
Date: Fri, 28 Nov 2025 17:36:50 -0300
Subject: [PATCH] docs: Add sidebar title collapse functionality and design
 facelift (#43754)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This PR adds the ability to collapse section in the docs sidebar (which
are persistent until you close the tab), and some design facelift to the
docs, which makes its design close to the site as well as polishing up
many elements and interactions (like moving the search to a modal and
making the table of content visible in smaller breakpoints).

<img width="600" height="2270" alt="Screenshot 2025-11-28 at 5  26@2x"
src="https://github.com/user-attachments/assets/3a8606c6-f74f-4bd2-84c8-d7a67ff97564"
/>

Release Notes:

- N/A
---
 docs/src/SUMMARY.md               |   2 +-
 docs/src/all-actions.md           |   2 +-
 docs/src/configuring-languages.md |   2 +-
 docs/theme/css/chrome.css         | 466 +++++++++++++++++-------------
 docs/theme/css/general.css        |  95 ++++--
 docs/theme/css/variables.css      |  47 ++-
 docs/theme/index.hbs              | 315 ++++++++++++--------
 docs/theme/page-toc.css           | 134 ++++-----
 docs/theme/page-toc.js            |   4 +
 docs/theme/plugins.js             | 122 +++++++-
 10 files changed, 768 insertions(+), 421 deletions(-)

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 5974b4f68d8951fa62b6bfaa625db5fdb38899fd..31a8462b15e9b74e2539de81e6e0f243abd5b790 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -1,6 +1,6 @@
 # Summary
 
-# Getting Started
+# Welcome
 
 - [Getting Started](./getting-started.md)
 - [Installation](./installation.md)
diff --git a/docs/src/all-actions.md b/docs/src/all-actions.md
index d20f7cfd63c01c03937c85e8f46476711c80e30f..e5a45a8fd8d5926e657d6ad35234fd14d4853952 100644
--- a/docs/src/all-actions.md
+++ b/docs/src/all-actions.md
@@ -1,3 +1,3 @@
-## All Actions
+# All Actions
 
 {#ACTIONS_TABLE#}
diff --git a/docs/src/configuring-languages.md b/docs/src/configuring-languages.md
index e478fab075acec67967a6c44cc5966e632aa1110..9185b679063a7e6c4d5026a6df448f8ac24f0a8b 100644
--- a/docs/src/configuring-languages.md
+++ b/docs/src/configuring-languages.md
@@ -1,4 +1,4 @@
-# Configuring supported languages
+# Configuring Supported Languages
 
 Zed offers powerful customization options for each programming language it supports. This guide will walk you through the various ways you can tailor your coding experience to your preferences and project requirements.
 
diff --git a/docs/theme/css/chrome.css b/docs/theme/css/chrome.css
index 9f2afad54388bf2289e57f43275cdf2b4d98d4dd..7b52b021923505b2d16d9b04f8eab4826f926947 100644
--- a/docs/theme/css/chrome.css
+++ b/docs/theme/css/chrome.css
@@ -13,160 +13,67 @@ a > .hljs {
   color: var(--links);
 }
 
-/*
-  body-container is necessary because mobile browsers don't seem to like
-  overflow-x on the body tag when there is a <meta name="viewport"> tag.
-*/
-#body-container {
-  /*
-      This is used when the sidebar pushes the body content off the side of
-      the screen on small screens. Without it, dragging on mobile Safari
-      will want to reposition the viewport in a weird way.
-  */
-  overflow-x: clip;
-}
-
-.large-logo-img {
-  display: block;
-}
-
 .icon-logo-img {
-  display: none;
+  display: block;
 }
 
-/* Menu Bar */
-
-#menu-bar,
-#menu-bar-hover-placeholder {
-  z-index: 101;
-  margin: auto calc(0px - var(--page-padding));
-}
-#menu-bar {
-  padding: 12px 16px;
-  position: relative;
-  display: flex;
-  flex-wrap: wrap;
-  background-color: var(--bg);
-  border-block-end-color: var(--bg);
-  border-block-end-width: 1px;
-  border-block-end-style: solid;
-}
-#menu-bar.sticky,
-.js #menu-bar-hover-placeholder:hover + #menu-bar,
-.js #menu-bar:hover,
-.js.sidebar-visible #menu-bar {
-  position: -webkit-sticky;
-  position: sticky;
-  top: 0 !important;
-}
-#menu-bar-hover-placeholder {
-  position: sticky;
-  position: -webkit-sticky;
-  top: 0;
-  height: var(--menu-bar-height);
-}
-#menu-bar.bordered {
-  border-block-end-color: var(--divider);
-}
-#menu-bar i,
-#menu-bar .icon-button {
+.icon-button {
   position: relative;
-  height: 3rem;
-  width: 3rem;
+  height: 28px;
+  width: 28px;
   z-index: 10;
   display: flex;
   align-items: center;
   justify-content: center;
   cursor: pointer;
   transition: color 0.5s;
-}
-#menu-bar .icon-button:hover {
-  background-color: var(--icon-btn-bg-hover);
+  border: 0;
+  background-color: transparent;
+  border-radius: 4px;
+  color: var(--icons);
 }
 
-@media only screen and (max-width: 420px) {
-  .large-logo-img {
-    display: none;
-  }
-
-  .icon-logo-img {
-    display: block;
-  }
-
-  #menu-bar {
-    padding: 12px;
-  }
-
-  #menu-bar .ib-hidden-mobile {
-    display: none;
-  }
-
-  .right-buttons {
-    width: 100px; /*For center aligning the icon link*/
-  }
+.icon-button:hover {
+  color: var(--icons-hover);
+  background-color: var(--icon-btn-bg-hover);
 }
 
-.icon-button {
-  border: none;
-  background: none;
-  padding: 0;
-  color: inherit;
-}
-.icon-button i {
-  margin: 0;
+.ib-hidden-desktop {
+  display: none;
 }
 
-.right-buttons {
+.header-bar {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  padding: 12px 24px;
+  background-color: var(--sidebar-bg);
+  border-bottom: 1px solid var(--divider);
   display: flex;
   align-items: center;
-  justify-content: end;
-}
-
-.right-buttons a {
-  text-decoration: none;
+  justify-content: space-between;
+  flex-shrink: 0;
 }
 
-.left-buttons {
+.header-bar .left-container {
+  width: 160px;
   display: flex;
   align-items: center;
-  gap: 0.5rem;
-}
-.no-js .left-buttons button {
-  display: none;
+  gap: 8px;
 }
 
-.menu-title {
-  display: inline-flex;
-  justify-content: center;
+.header-bar .right-container {
+  width: 160px;
+  display: flex;
   align-items: center;
-  flex: 1;
-  overflow: hidden;
-  filter: var(--logo-brightness);
-}
-.js .menu-title {
-  cursor: pointer;
+  gap: 4px;
 }
 
-.menu-bar,
-.menu-bar:visited,
-.nav-chapters,
-.nav-chapters:visited,
-.mobile-nav-chapters,
-.mobile-nav-chapters:visited,
-.menu-bar .icon-button,
-.menu-bar a i {
-  color: var(--icons);
-}
-
-.menu-bar i:hover,
-.menu-bar .icon-button:hover,
-.nav-chapters:hover,
-.mobile-nav-chapters i:hover {
-  color: var(--icons-hover);
+.logo-nav {
+  display: block;
+  filter: var(--logo-brightness);
 }
 
-/* Nav Icons */
-
 .nav-chapters {
   font-size: 2.5em;
   text-align: center;
@@ -353,7 +260,7 @@ pre > .buttons button {
   border-width: 1px;
   border-radius: 4px;
   border-color: var(--border);
-  background-color: var(--theme-popup-bg);
+  background-color: var(--popover-bg);
   transition: 100ms;
   transition-property: color, border-color, background-color;
   color: var(--icons);
@@ -444,6 +351,8 @@ mark.fade-out {
 #searchbar:focus,
 #searchbar.active {
   box-shadow: 0 0 3px var(--searchbar-shadow-color);
+  outline: none;
+  border-color: var(--search-mark-bg);
 }
 
 .searchresults-header {
@@ -492,20 +401,21 @@ ul#searchresults span.teaser em {
 /* Sidebar */
 
 .sidebar {
-  position: fixed;
-  left: 0;
-  top: 0;
-  bottom: 0;
+  position: relative;
   width: var(--sidebar-width);
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
   font-size: 0.875em;
   box-sizing: border-box;
   -webkit-overflow-scrolling: touch;
-  overscroll-behavior-y: contain;
+  overscroll-behavior-y: none;
+  overflow: hidden;
   background-color: var(--sidebar-bg);
   color: var(--sidebar-fg);
-  border-right: 1px solid;
-  border-color: var(--divider);
+  border-right: 1px solid var(--divider);
 }
+
 [dir="rtl"] .sidebar {
   left: unset;
   right: 0;
@@ -524,14 +434,11 @@ ul#searchresults span.teaser em {
   line-height: 2em;
 }
 .sidebar .sidebar-scrollbox {
+  flex: 1;
   overflow-y: auto;
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  left: 0;
-  right: 0;
-  padding: 12px 12px 12px 24px;
+  min-height: 0;
 }
+
 .sidebar .sidebar-resize-handle {
   position: absolute;
   cursor: col-resize;
@@ -561,18 +468,6 @@ ul#searchresults span.teaser em {
       var(--sidebar-resize-indicator-space)
   );
 }
-/* sidebar-hidden */
-#sidebar-toggle-anchor:not(:checked) ~ .sidebar {
-  transform: translateX(
-    calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width))
-  );
-  z-index: -1;
-}
-[dir="rtl"] #sidebar-toggle-anchor:not(:checked) ~ .sidebar {
-  transform: translateX(
-    calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width))
-  );
-}
 .sidebar::-webkit-scrollbar {
   background: var(--sidebar-bg);
 }
@@ -580,30 +475,38 @@ ul#searchresults span.teaser em {
   background: var(--scrollbar);
 }
 
-/* sidebar-visible */
-#sidebar-toggle-anchor:checked ~ .page-wrapper {
-  transform: translateX(
-    calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width))
-  );
-}
-[dir="rtl"] #sidebar-toggle-anchor:checked ~ .page-wrapper {
-  transform: translateX(
-    calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width))
-  );
+@media only screen and (max-width: 619px) {
+  .sidebar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    height: 100vh;
+    padding-top: 57px; /* Account for header height */
+    transform: translateX(-100%);
+    z-index: 99;
+    transition: transform 0.1s ease;
+  }
+
+  [dir="rtl"] .sidebar {
+    left: unset;
+    right: 0;
+    transform: translateX(100%);
+  }
+
+  body.sidebar-open .sidebar {
+    transform: translateX(0);
+  }
 }
+
 @media only screen and (min-width: 620px) {
-  #sidebar-toggle-anchor:checked ~ .page-wrapper {
-    transform: none;
-    margin-inline-start: var(--sidebar-width);
-  }
-  [dir="rtl"] #sidebar-toggle-anchor:checked ~ .page-wrapper {
-    transform: none;
+  .sidebar {
+    position: relative;
   }
 }
 
 .chapter {
   list-style: none outside none;
-  padding-inline-start: 0;
+  padding: 8px 20px 20px 20px;
   line-height: 2.2em;
   margin: 0;
 }
@@ -616,9 +519,10 @@ ul#searchresults span.teaser em {
   display: flex;
   color: var(--sidebar-non-existant);
 }
+
 .chapter li a {
   display: block;
-  padding: 0;
+  padding: 0 4px;
   text-decoration: none;
   color: var(--sidebar-fg);
 }
@@ -634,67 +538,95 @@ ul#searchresults span.teaser em {
 
 .chapter li > a.toggle {
   cursor: pointer;
-  display: block;
+  display: flex;
+  align-items: center;
+  justify-content: center;
   margin-inline-start: auto;
-  padding: 0 10px;
   user-select: none;
-  opacity: 0.68;
-}
-
-.chapter li > a.toggle div {
-  transition: transform 0.5s;
+  opacity: 0.5;
+  border-radius: 4px;
+  transition:
+    opacity 0.15s ease,
+    background-color 0.15s ease;
 }
 
-/* collapse the section */
-.chapter li:not(.expanded) + li > ol {
-  display: none;
+.chapter li > a.toggle:hover {
+  opacity: 1;
+  background-color: var(--theme-hover);
 }
 
 .chapter li.chapter-item {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
   line-height: 1.5em;
   margin-block-start: 0.6em;
 }
 
+.chapter li.chapter-item > a:first-child {
+  flex: 1;
+  min-width: 0;
+}
+
 .chapter li.expanded > a.toggle div {
   transform: rotate(90deg);
 }
 
-.spacer {
-  width: 100%;
-  height: 3px;
-  margin: 5px 0px;
+.chapter li.part-title {
+  font-size: 1.4rem;
+  padding: 0 8px 0 4px;
+  color: var(--title-color);
+  cursor: pointer;
+  user-select: none;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  line-height: auto;
+  border-radius: 2px;
 }
-.chapter .spacer {
-  background-color: var(--divider);
+
+.chapter li.part-title.collapsible:hover {
+  background-color: var(--hover-section-title);
 }
 
-@media (-moz-touch-enabled: 1), (pointer: coarse) {
-  .chapter li a {
-    padding: 5px 0;
-  }
-  .spacer {
-    margin: 10px 0;
-  }
+.chapter li.part-title.collapsible::after {
+  content: "❯";
+  display: inline-block;
+  font-size: 1.2rem;
+  opacity: 0.6;
+  transition: transform 0.2s ease;
+  flex-shrink: 0;
+}
+
+.chapter li.part-title.collapsible.expanded::after {
+  transform: rotate(90deg);
+}
+
+.chapter li.section-spacer {
+  height: 2rem;
+  list-style: none;
+}
+
+.chapter li.section-hidden {
+  display: none !important;
 }
 
 .section {
   list-style: none outside none;
-  padding-inline-start: 20px;
+  padding-inline-start: 3ch;
   line-height: 1.9em;
 }
 
-/* Theme Menu Popup */
-
 .theme-popup {
   position: absolute;
-  left: 32px;
-  top: calc(var(--menu-bar-height) - 12px);
+  right: 155px;
+  top: calc(var(--menu-bar-height) - 18px);
   z-index: 1000;
   border-radius: 4px;
   font-size: 1.4rem;
   color: var(--fg);
-  background: var(--theme-popup-bg);
-  border: 1px solid var(--theme-popup-border);
+  background: var(--popover-bg);
+  border: 1px solid var(--popover-border);
   margin: 0;
   padding: 0;
   list-style: none;
@@ -702,6 +634,7 @@ ul#searchresults span.teaser em {
   /* Don't let the children's background extend past the rounded corners. */
   overflow: hidden;
 }
+
 [dir="rtl"] .theme-popup {
   left: unset;
   right: 10px;
@@ -737,6 +670,8 @@ ul#searchresults span.teaser em {
 }
 
 .download-button {
+  max-height: 28px;
+  margin-left: 8px;
   background: var(--download-btn-bg);
   color: var(--download-btn-color);
   padding: 4px 8px;
@@ -745,6 +680,7 @@ ul#searchresults span.teaser em {
   font-size: 1.4rem;
   border-radius: 4px;
   box-shadow: var(--download-btn-shadow) 0px -2px 0px 0px inset;
+  text-decoration: none;
   transition: 100ms;
   transition-property: box-shadow, border-color, background-color;
 }
@@ -754,3 +690,135 @@ ul#searchresults span.teaser em {
   border-color: var(--download-btn-border-hover);
   box-shadow: none;
 }
+
+.search-button {
+  min-width: 100px;
+  max-width: 300px;
+  height: 28px;
+  width: 100%;
+  padding: 4px 4px 4px 8px;
+  display: flex;
+  gap: 8px;
+  background: var(--search-btn-bg);
+  border: 1px solid;
+  border-color: var(--search-btn-border);
+  font-size: 1.4rem;
+  font-family: var(--font);
+  color: var(--icons);
+  border-radius: 4px;
+  transition: 100ms;
+  transition-property: box-shadow, border-color, background-color;
+}
+
+.search-button:hover {
+  background: var(--search-btn-bg-hover);
+}
+
+.search-button .icon {
+  width: 12px;
+  height: 12px;
+  transform: translateY(10%);
+  scale: 0.9;
+}
+
+.search-content-desktop {
+  width: 100%;
+  display: flex;
+  justify-content: space-between;
+}
+
+.search-content-mobile {
+  display: none;
+}
+
+.search-container {
+  box-sizing: border-box;
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  padding: 24px;
+  padding-top: 72px;
+  background-color: rgba(0, 0, 0, 0.5);
+  display: none;
+  justify-content: center;
+}
+
+.search-container:has(#search-wrapper:not(.hidden)) {
+  display: flex;
+}
+
+.search-modal {
+  box-sizing: border-box;
+
+  max-width: 600px;
+  min-width: 600px;
+  height: fit-content;
+  max-height: 600px;
+  display: flex;
+  flex-direction: column;
+  padding: 16px;
+  overflow-y: auto;
+
+  border-radius: 8px;
+  background: var(--popover-bg);
+  border: 1px solid var(--popover-border);
+  box-shadow: var(--popover-shadow);
+}
+
+.searchbar-outer {
+  width: 100%;
+}
+
+@media only screen and (max-width: 780px) {
+  .header-bar {
+    padding: 16px;
+    justify-content: start;
+  }
+
+  .download-button {
+    display: none;
+  }
+
+  .ib-hidden-mobile {
+    display: none;
+  }
+
+  .header-bar .left-container {
+    width: fit-content;
+  }
+
+  .header-bar .right-container {
+    width: fit-content;
+  }
+
+  .search-button {
+    width: 100px;
+    margin-left: auto;
+    margin-right: 8px;
+  }
+
+  .ib-hidden-desktop {
+    display: block;
+  }
+
+  .search-modal {
+    width: 90vw;
+    min-width: auto;
+  }
+
+  .search-content-desktop {
+    display: none;
+  }
+
+  .search-content-mobile {
+    display: flex;
+  }
+
+  .sidebar {
+    box-shadow: var(--sidebar-mobile-shadow);
+  }
+
+  .theme-popup {
+    right: 15px;
+  }
+}
diff --git a/docs/theme/css/general.css b/docs/theme/css/general.css
index df20d35b53ebb173140e63ebfa0175236236ee14..c7942253656e246912f3e52be8d8eeeeb203632a 100644
--- a/docs/theme/css/general.css
+++ b/docs/theme/css/general.css
@@ -23,7 +23,16 @@ html {
 body {
   margin: 0;
   font-size: 1.6rem;
-  overflow-x: hidden;
+  overflow: hidden;
+  height: 100vh;
+  overscroll-behavior-y: none;
+}
+
+#body-container {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  overflow: hidden;
 }
 
 code {
@@ -37,6 +46,17 @@ main {
   overflow-wrap: break-word;
 }
 
+.noise-pattern {
+  pointer-events: none;
+  user-select: none;
+  z-index: 105;
+  position: absolute;
+  inset: 0;
+  background-size: 180px;
+  background-repeat: repeat;
+  opacity: var(--noise-opacity);
+}
+
 /* make wide tables scroll if they overflow */
 .table-wrapper {
   overflow-x: auto;
@@ -91,6 +111,9 @@ h2 {
 
 h3 {
   font-size: 2rem;
+  padding-bottom: 0.8rem;
+  border-bottom: 1px dashed;
+  border-color: var(--border-light);
 }
 
 h4 {
@@ -109,6 +132,14 @@ h5 {
   margin-block-end: 0;
 }
 
+code:focus-visible,
+pre:focus-visible,
+li:focus-visible,
+button:focus-visible,
+a:focus-visible {
+  outline: 3px solid #094ece80;
+}
+
 .header + .header h3,
 .header + .header h4,
 .header + .header h5 {
@@ -144,17 +175,27 @@ hr {
   scroll-margin-top: calc(var(--menu-bar-height) + 2rem);
 }
 
-.page {
-  outline: 0;
-  padding: 0 var(--page-padding);
-  margin-block-start: calc(
-    0px - var(--menu-bar-height)
-  ); /* Compensate for the #menu-bar-hover-placeholder */
-}
 .page-wrapper {
   box-sizing: border-box;
   background-color: var(--bg);
+  display: flex;
+  flex: 1;
+  overflow: hidden;
+  min-height: 0;
+}
+
+.page {
+  outline: 0;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior-y: none;
+  min-width: 0;
+  position: relative;
 }
+
 .no-js .page-wrapper,
 .js:not(.sidebar-resizing) .page-wrapper {
   transition:
@@ -168,18 +209,23 @@ hr {
 }
 
 .content {
-  overflow-y: auto;
-  padding: 48px 4px;
+  padding: 48px 32px 0 32px;
+  display: flex;
+  justify-content: space-between;
+  gap: 36px;
 }
+
 .content main {
   margin-inline-start: auto;
   margin-inline-end: auto;
   max-width: var(--content-max-width);
 }
+
 .content p {
   line-height: 1.625em;
 }
 .content div.video {
+  z-index: 150;
   margin-top: 1rem;
   border: 1px solid;
   border-color: var(--border);
@@ -213,6 +259,8 @@ hr {
 }
 .content img,
 .content video {
+  position: relative;
+  z-index: 150;
   max-width: 100%;
   background-color: var(--media-bg);
   border: 1px solid;
@@ -333,7 +381,7 @@ blockquote .warning:before {
 kbd {
   background-color: rgba(8, 76, 207, 0.1);
   border-radius: 4px;
-  border: solid 1px var(--theme-popup-border);
+  border: solid 1px var(--popover-border);
   box-shadow: inset 0 -1px 0 var(--theme-hover);
   display: inline-block;
   font-size: var(--code-font-size);
@@ -378,15 +426,6 @@ kbd {
   visibility: visible;
 }
 
-.chapter li.part-title {
-  font-size: 18px;
-  font-family: var(--title-font);
-  font-weight: 520;
-  color: var(--title-color);
-  margin: 5px 0;
-  margin-top: 2rem;
-}
-
 .result-no-output {
   font-style: italic;
 }
@@ -395,3 +434,19 @@ code:not(pre code).hljs {
   color: var(--code-text) !important;
   background-color: var(--code-bg) !important;
 }
+
+@media only screen and (max-width: 1020px) {
+  .content {
+    padding: 16px 32px 0 32px;
+  }
+
+  .content main {
+    width: 100%;
+  }
+}
+
+@media only screen and (max-width: 400px) {
+  .content {
+    padding: 16px 16px 0 16px;
+  }
+}
diff --git a/docs/theme/css/variables.css b/docs/theme/css/variables.css
index dceba25af87e62ee64459984950d3e6921421d39..01a104d4d88dafde868f37c6bb3e9907248cdc71 100644
--- a/docs/theme/css/variables.css
+++ b/docs/theme/css/variables.css
@@ -5,11 +5,11 @@
 
   --logo-brightness: brightness(1);
 
-  --sidebar-width: 300px;
+  --sidebar-width: 280px;
   --sidebar-resize-indicator-width: 0px;
   --sidebar-resize-indicator-space: 2px;
   --page-padding: 15px;
-  --content-max-width: 750px;
+  --content-max-width: 690px;
   --menu-bar-height: 64px;
   --font: "IA Writer Quattro S", sans-serif;
   --title-font: "Lora", "Helvetica Neue", Helvetica, Arial, sans-serif;
@@ -19,6 +19,7 @@
   --code-font-size: 0.875em
     /* please adjust the ace font size accordingly in editor.js */;
 
+  --noise-opacity: 0.024;
   --bg: hsla(50, 25%, 96%);
   --fg: hsl(220, 13%, 34%);
   --title-color: hsl(220, 92%, 42%);
@@ -29,12 +30,14 @@
 
   --media-bg: hsl(50, 25%, 92%);
 
+  --sidebar-bg: hsla(50, 25%, 94%);
   --sidebar-fg: hsl(0, 0%, 0%);
   --sidebar-non-existant: #aaaaaa;
   --sidebar-active: hsl(220, 93%, 42%);
   --sidebar-active-bg: hsl(220, 93%, 42%, 0.1);
+  --sidebar-mobile-shadow: 0px 16px 16px hsl(0, 0%, 0%, 0.1);
 
-  --divider: hsl(220, 93%, 42%, 0.15);
+  --divider: hsl(220, 50%, 45%, 0.1);
   --scrollbar: #8f8f8f;
 
   --icons: #747474;
@@ -56,9 +59,13 @@
   --pre-border: hsla(220, 93%, 42%, 0.3);
   --pre-shadow: hsla(220, 93%, 42%, 0.07);
 
-  --theme-popup-bg: #fafafa;
-  --theme-popup-border: #cccccc;
+  --popover-bg: #fafafa;
+  --popover-border: #cccccc;
+  --popover-shadow:
+    0 10px 15px -3px hsl(0, 0%, 0%, 0.1), 0 4px 6px -4px hsl(0, 0%, 0%, 0.1);
+
   --theme-hover: #e6e6e6;
+  --hover-section-title: hsl(50, 25%, 88%);
 
   --quote-bg: hsl(197, 37%, 96%);
   --quote-border: hsl(197, 37%, 84%);
@@ -71,6 +78,9 @@
   --table-border-color: hsl(220, 93%, 42%, 0.15);
   --table-alternate-bg: hsl(220, 10%, 90%, 0.4);
 
+  --toc-link-underline: hsl(0, 0%, 0%, 0.1);
+  --toc-link-underline-hover: hsl(0, 0%, 0%, 0.5);
+
   --searchbar-border-color: #aaa;
   --searchbar-bg: #fafafa;
   --searchbar-fg: #000;
@@ -87,6 +97,10 @@
   --download-btn-border-hover: hsla(220, 60%, 50%, 0.2);
   --download-btn-shadow: hsla(220, 40%, 60%, 0.1);
 
+  --search-btn-bg: hsl(220, 100%, 100%);
+  --search-btn-bg-hover: hsla(50, 25%, 97%);
+  --search-btn-border: hsl(220, 50%, 45%, 0.2);
+
   --toast-bg: hsla(220, 93%, 98%);
   --toast-border: hsla(220, 93%, 42%, 0.3);
   --toast-border-success: hsla(120, 73%, 42%, 0.3);
@@ -103,7 +117,8 @@
 
   --logo-brightness: brightness(2);
 
-  --bg: hsl(220, 13%, 10%);
+  --noise-opacity: 0.012;
+  --bg: hsl(220, 13%, 7.5%);
   --fg: hsl(220, 14%, 70%);
   --title-color: hsl(220, 92%, 80%);
 
@@ -113,13 +128,14 @@
 
   --media-bg: hsl(220, 13%, 8%);
 
-  --sidebar-bg: hsl(220, 13%, 10%);
+  --sidebar-bg: hsl(220, 13%, 6.5%);
   --sidebar-fg: hsl(220, 14%, 71%);
   --sidebar-non-existant: #505254;
   --sidebar-active: hsl(220, 92%, 75%);
   --sidebar-active-bg: hsl(220, 93%, 42%, 0.25);
+  --sidebar-mobile-shadow: 0px 16px 16px hsl(0, 0%, 0%, 0.6);
 
-  --divider: hsl(220, 13%, 20%);
+  --divider: hsl(220, 13%, 12%);
   --scrollbar: hsl(220, 13%, 30%);
 
   --icons: hsl(220, 14%, 71%);
@@ -140,9 +156,13 @@
   --pre-border: hsla(220, 93%, 70%, 0.3);
   --pre-shadow: hsla(220, 93%, 70%, 0.1);
 
-  --theme-popup-bg: hsl(220, 13%, 15%);
-  --theme-popup-border: hsl(220, 13%, 20%);
+  --popover-bg: hsl(220, 13%, 8%);
+  --popover-border: hsl(220, 13%, 20%);
+  --popover-shadow:
+    0 10px 15px -3px hsl(0, 0%, 0%, 0.1), 0 4px 6px -4px hsl(0, 0%, 0%, 0.1);
+
   --theme-hover: hsl(220, 13%, 25%);
+  --hover-section-title: hsl(220, 13%, 11%);
 
   --quote-bg: hsl(220, 13%, 25%, 0.4);
   --quote-border: hsl(220, 13%, 32%, 0.5);
@@ -151,6 +171,9 @@
   --table-header-bg: hsl(220, 13%, 25%, 0.5);
   --table-alternate-bg: hsl(220, 13%, 20%, 0.4);
 
+  --toc-link-underline: hsl(255, 100%, 100%, 0.1);
+  --toc-link-underline-hover: hsl(255, 100%, 100%, 0.4);
+
   --warning-border: hsl(25, 100%, 85%, 0.2);
   --warning-bg: hsl(42, 100%, 40%, 0.1);
   --warning-icon: hsl(42, 100%, 80%);
@@ -171,6 +194,10 @@
   --download-btn-border-hover: hsla(220, 90%, 80%, 0.4);
   --download-btn-shadow: hsla(220, 50%, 60%, 0.15);
 
+  --search-btn-bg: hsl(220, 90%, 90%, 0.05);
+  --search-btn-bg-hover: hsl(220, 90%, 90%, 0.1);
+  --search-btn-border: hsla(220, 90%, 80%, 0.1);
+
   --toast-bg: hsla(220, 20%, 98%, 0.05);
   --toast-border: hsla(220, 93%, 70%, 0.2);
   --toast-border-success: hsla(120, 90%, 60%, 0.3);
diff --git a/docs/theme/index.hbs b/docs/theme/index.hbs
index 052d983483708699333c6ca308509d306cbc7566..8ac33ea0d7b2e3ae1730a3bc3e210a24466a0811 100644
--- a/docs/theme/index.hbs
+++ b/docs/theme/index.hbs
@@ -48,8 +48,10 @@
         <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
         {{/if}}
     </head>
-    <body class="sidebar-visible no-js">
+    <body class="no-js">
     <div id="body-container">
+        <div class="noise-pattern" style="background-image: url('https://cdn.zed.dev/images/noise.png');"></div>
+
         <!-- Provide site root to javascript -->
         <script>
             var path_to_root = "{{ path_to_root }}";
@@ -71,138 +73,214 @@
             body.classList.add('js');
         </script>
 
-        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
-
-        <!-- Hide / unhide sidebar before it is displayed -->
-        <script>
-            var body = document.querySelector('body');
-            var sidebar = null;
-            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
-            if (document.body.clientWidth >= 1080) {
-                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
-                sidebar = sidebar || 'visible';
-            } else {
-                sidebar = 'hidden';
-            }
-            sidebar_toggle.checked = sidebar === 'visible';
-            body.classList.remove('sidebar-visible');
-            body.classList.add("sidebar-" + sidebar);
-        </script>
-
-        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
-            <div class="sidebar-scrollbox">
-                {{#toc}}{{/toc}}
+        <header class="header-bar">
+            <div class="left-container">
+                <a href="/" class="logo-nav">
+                    <img src="https://zed.dev/logo_icon.webp" class="icon-logo-img" alt="Zed Industries" style="height: 26px;">
+                </a>
+                <button id="sidebar-toggle" class="icon-button ib-hidden-desktop" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar" aria-expanded="false">
+                    <i class="fa fa-bars"></i>
+                </button>
             </div>
-            <div style="display: none;" id="sidebar-resize-handle" class="sidebar-resize-handle">
-                <div class="sidebar-resize-indicator"></div>
+            {{#if search_enabled}}
+            <button id="search-toggle" class="search-button" type="button" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                <i class="icon fa fa-search"></i>
+                <span class="search-content-desktop">
+                    <span class="placeholder">Search docs…</span>
+                    <kbd>S</kbd>
+                </span>
+                <span class="search-content-mobile">
+                    <span class="placeholder">Search…</span>
+                </span>
+            </button>
+            {{/if}}
+            <div class="right-container">
+                <button id="theme-toggle" class="icon-button" type="button" title="Change Theme" aria-label="Change Theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                    <i class="fa fa-paint-brush"></i>
+                </button>
+
+                <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                    <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                    <li role="none"><button role="menuitem" class="theme" id="dark">Dark</button></li>
+                </ul>
+
+                <button id="copy-markdown-toggle" class="icon-button ib-hidden-mobile" type="button" title="Copy Page as Markdown" aria-label="Copy page as markdown">
+                    <i class="fa fa-copy"></i>
+                </button>
+
+                <a class="download-button" href="https://zed.dev/download" title="Download Zed" aria-label="Download Zed">
+                    Download
+                </a>
+                {{#if git_repository_url}}
+                <a href="{{git_repository_url}}" title="Git repository" aria-label="Git repository">
+                    <i id="git-repository-button" class="fa {{git_repository_icon}}"></i>
+                </a>
+                {{/if}}
+                {{#if git_repository_edit_url}}
+                <a href="{{git_repository_edit_url}}" title="Suggest an edit" aria-label="Suggest an edit">
+                    <i id="git-edit-button" class="fa fa-edit"></i>
+                </a>
+                {{/if}}
             </div>
-        </nav>
-
-        <!-- Track and set sidebar scroll position -->
-        <script>
-            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
-            sidebarScrollbox.addEventListener('click', function(e) {
-                if (e.target.tagName === 'A') {
-                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
-                }
-            }, { passive: true });
-            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
-            sessionStorage.removeItem('sidebar-scroll');
-            if (sidebarScrollTop) {
-                // preserve sidebar scroll position when navigating via links within sidebar
-                sidebarScrollbox.scrollTop = sidebarScrollTop;
-            } else {
-                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
-                var activeSection = document.querySelector('#sidebar .active');
-                if (activeSection) {
-                    activeSection.scrollIntoView({ block: 'center' });
-                }
-            }
-        </script>
+        </header>
 
         <div id="page-wrapper" class="page-wrapper">
-            <div class="page">
-                {{> header}}
-                <div id="menu-bar-hover-placeholder"></div>
-                <div id="menu-bar" class="menu-bar sticky">
-                    <div class="left-buttons">
-
-                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
-                            <i class="fa fa-bars"></i>
-                        </label>
-
-                        <button id="theme-toggle" class="icon-button" type="button" title="Change Theme" aria-label="Change Theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
-                            <i class="fa fa-paint-brush"></i>
-                        </button>
-                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
-                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
-                            <li role="none"><button role="menuitem" class="theme" id="dark">Dark</button></li>
-                        </ul>
-
-                        <button id="copy-markdown-toggle" class="icon-button ib-hidden-mobile" type="button" title="Copy Page as Markdown" aria-label="Copy page as markdown">
-                            <i class="fa fa-copy"></i>
-                        </button>
 
-                        {{#if search_enabled}}
-                        <button id="search-toggle" class="icon-button" type="button" title="Search (s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
-                            <i class="fa fa-search"></i>
-                        </button>
-                        {{/if}}
-                    </div>
-
-                    <header class="menu-title">
-                        <a href="/">
-                            <img src="https://zed.dev/logo_wordmark_1500.webp" class="large-logo-img" alt="Zed Industries" style="height: 28px;">
-                            <img src="https://zed.dev/logo_icon.webp" class="icon-logo-img" alt="Zed Industries" style="height: 28px;">
-                        </a>
-                    </header>
-
-                    <div class="right-buttons">
-                        <a class="download-button" href="https://zed.dev/download" title="Download Zed" aria-label="Download Zed">
-                            Download
-                        </a>
-                        {{#if git_repository_url}}
-                        <a href="{{git_repository_url}}" title="Git repository" aria-label="Git repository">
-                            <i id="git-repository-button" class="fa {{git_repository_icon}}"></i>
-                        </a>
-                        {{/if}}
-                        {{#if git_repository_edit_url}}
-                        <a href="{{git_repository_edit_url}}" title="Suggest an edit" aria-label="Suggest an edit">
-                            <i id="git-edit-button" class="fa fa-edit"></i>
-                        </a>
-                        {{/if}}
-                    </div>
-                </div>
-
-                {{#if search_enabled}}
-                <div id="search-wrapper" class="hidden">
+            {{#if search_enabled}}
+            <div class="search-container">
+                <div id="search-wrapper" class="search-modal hidden">
                     <form id="searchbar-outer" class="searchbar-outer">
-                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search…" aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                     </form>
-                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                    <div id="searchresults-outer" class="searchresults-outer">
                         <div id="searchresults-header" class="searchresults-header"></div>
                         <ul id="searchresults">
                         </ul>
                     </div>
                 </div>
-                {{/if}}
+            </div>
+            {{/if}}
+
+            <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+                <div class="sidebar-scrollbox">
+                    {{#toc}}{{/toc}}
+                </div>
+                <div style="display: none;" id="sidebar-resize-handle" class="sidebar-resize-handle">
+                    <div class="sidebar-resize-indicator"></div>
+                </div>
+            </nav>
+
+            <!-- Mobile sidebar toggle -->
+            <script>
+                (function() {
+                    var sidebarToggle = document.getElementById('sidebar-toggle');
+                    var sidebar = document.getElementById('sidebar');
+
+                    sidebarToggle.addEventListener('click', function() {
+                        var isOpen = document.body.classList.toggle('sidebar-open');
+                        sidebarToggle.setAttribute('aria-expanded', isOpen);
+                        sidebar.setAttribute('aria-hidden', !isOpen);
+                    });
 
-                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
-                <script>
-                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
-                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
-                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
-                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    // Close sidebar when clicking a link inside it (on mobile)
+                    sidebar.addEventListener('click', function(e) {
+                        if (e.target.tagName === 'A' && window.innerWidth < 620) {
+                            document.body.classList.remove('sidebar-open');
+                            sidebarToggle.setAttribute('aria-expanded', 'false');
+                            sidebar.setAttribute('aria-hidden', 'true');
+                        }
+                    });
+                })();
+            </script>
+
+            <!-- Search backdrop handlers -->
+            <script>
+                (function() {
+                    var searchWrapper = document.getElementById('search-wrapper');
+                    var searchContainer = document.querySelector('.search-container');
+                    var searchResults = document.getElementById('searchresults');
+
+                    if (!searchWrapper || !searchContainer) return;
+
+                    searchContainer.addEventListener('click', function(e) {
+                        if (e.target === searchContainer) {
+                            searchWrapper.classList.add('hidden');
+                        }
                     });
-                </script>
 
+                    if (searchResults) {
+                        searchResults.addEventListener('click', function(e) {
+                            if (e.target.tagName === 'A' || e.target.closest('a')) {
+                                searchWrapper.classList.add('hidden');
+                            }
+                        });
+                    }
+                })();
+            </script>
+
+            <!-- Insert section spacers and apply collapsed state before scroll restoration to prevent layout shift/flicker -->
+            <script>
+                (function() {
+                    var chapterList = document.querySelector('#sidebar ol.chapter');
+                    if (!chapterList) return;
+
+                    var collapsedSections = [];
+                    try {
+                        var stored = sessionStorage.getItem('sidebar-collapsed-sections');
+                        if (stored) {
+                            collapsedSections = JSON.parse(stored);
+                        }
+                    } catch (e) {}
+
+                    var partTitles = chapterList.querySelectorAll('li.part-title');
+                    var previousPartTitle = null;
+
+                    partTitles.forEach(function(partTitle, index) {
+                        partTitle._sectionName = partTitle.textContent.trim();
+
+                        // Insert a spacer before this part-title (except for the first one)
+                        if (index > 0) {
+                            var spacer = document.createElement('li');
+                            spacer.className = 'section-spacer';
+                            partTitle.parentNode.insertBefore(spacer, partTitle);
+
+                            if (previousPartTitle) {
+                                previousPartTitle._spacerAfter = spacer;
+                            }
+                        }
+
+                        var isCollapsed = collapsedSections.includes(partTitle._sectionName);
+                        if (isCollapsed) {
+                            // Hide all siblings until next part-title
+                            var sibling = partTitle.nextElementSibling;
+                            while (sibling && !sibling.classList.contains('part-title')) {
+                                sibling.classList.add('section-hidden');
+                                sibling = sibling.nextElementSibling;
+                            }
+                            // Hide the spacer after this section (will be set on next iteration)
+                            partTitle._isCollapsed = true;
+                        }
+
+                        // If previous section was collapsed, hide its spacer
+                        if (previousPartTitle && previousPartTitle._isCollapsed && previousPartTitle._spacerAfter) {
+                            previousPartTitle._spacerAfter.classList.add('section-hidden');
+                        }
+
+                        previousPartTitle = partTitle;
+                    });
+
+                    // Handle the last section's spacer if it was collapsed
+                    if (previousPartTitle && previousPartTitle._isCollapsed && previousPartTitle._spacerAfter) {
+                        previousPartTitle._spacerAfter.classList.add('section-hidden');
+                    }
+                })();
+            </script>
+
+            <!-- Track and set sidebar scroll position -->
+            <script>
+                var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+                sidebarScrollbox.addEventListener('click', function(e) {
+                    if (e.target.tagName === 'A') {
+                        sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                    }
+                }, { passive: true });
+                var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+                sessionStorage.removeItem('sidebar-scroll');
+                if (sidebarScrollTop) {
+                    // preserve sidebar scroll position when navigating via links within sidebar
+                    sidebarScrollbox.scrollTop = sidebarScrollTop;
+                } else {
+                    // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                    var activeSection = document.querySelector('#sidebar .active');
+                    if (activeSection) {
+                        activeSection.scrollIntoView({ block: 'center' });
+                    }
+                }
+            </script>
+
+            <div class="page">
                 <div id="content" class="content">
                     <main>
-                      <div class="sidetoc">
-                          <nav class="pagetoc">
-                            <p class="toc-title">On this page</p>
-                          </nav>
-                      </div>
                       {{{ content }}}
                         <div class="footer-buttons">
                             {{#previous}}
@@ -219,6 +297,11 @@
                             {{/next}}
                         </div>
                     </main>
+                    <div class="toc-container">
+                        <nav class="pagetoc">
+                            <p class="toc-title">On this page</p>
+                        </nav>
+                    </div>
                 </div>
             </div>
         </div>
diff --git a/docs/theme/page-toc.css b/docs/theme/page-toc.css
index c8210e9a29fbda26f00cf6cc7639969a7b6ffd45..ce9beea43c52b797a29a8c0df1dcf5f45ab1fd95 100644
--- a/docs/theme/page-toc.css
+++ b/docs/theme/page-toc.css
@@ -1,77 +1,67 @@
-@media only screen and (max-width: 1674px) {
-  .sidetoc {
-    display: none;
-  }
+.pagetoc {
+  box-sizing: border-box;
+  position: sticky;
+  top: 50px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  width: 220px;
+  padding: 28px 0 120px 0;
+  max-height: calc(100svh - 50px);
+  overflow-x: hidden;
+}
+.pagetoc > :last-child {
+  margin-bottom: 16px;
+}
+.pagetoc a {
+  width: fit-content;
+  font-size: 1.4rem;
+  color: var(--fg) !important;
+  display: inline-block;
+  padding: 2px 0;
+  text-align: left;
+  text-decoration: underline;
+  text-decoration-color: var(--toc-link-underline);
+}
+.pagetoc a:hover {
+  text-decoration-color: var(--toc-link-underline-hover);
+}
+.pagetoc a.active {
+  background-color: var(--sidebar-active-bg);
+  color: var(--sidebar-active) !important;
+  text-decoration-color: hsl(219, 93%, 42%, 0.1);
+}
+.pagetoc a.active:hover {
+  text-decoration-color: hsl(219, 93%, 42%, 0.8);
+}
+.pagetoc .active {
+  background: var(--sidebar-bg);
+  color: var(--sidebar-fg);
+}
+.pagetoc .pagetoc-H1 {
+  display: none;
+}
+.pagetoc .pagetoc-H3 {
+  margin-left: 2ch;
+}
+.pagetoc .pagetoc-H4 {
+  margin-left: 4ch;
+}
+.pagetoc .pagetoc-H5 {
+  display: none;
+}
+.pagetoc .pagetoc-H6 {
+  display: none;
+}
+.toc-title {
+  margin: 0;
+  margin-bottom: 6px;
+  font-size: 1.4rem;
+  color: var(--full-contrast);
 }
 
-@media only screen and (min-width: 1675px) {
-  main {
-    position: relative;
-  }
-  .sidetoc {
-    margin-left: auto;
-    margin-right: auto;
-    left: calc(100% + (var(--content-max-width)) / 3 - 160px);
-    position: absolute;
-  }
-  .pagetoc {
-    position: fixed;
-    top: 64px;
-    width: 220px;
-    height: calc(100vh - var(--menu-bar-height) - 0.67em * 4);
-    padding: 80px 16px 40px 0;
-    overflow: auto;
-  }
-  .pagetoc > :last-child {
-    margin-bottom: 64px;
-  }
-  .pagetoc a {
-    width: fit-content;
-    font-size: 1.4rem;
-    border-left: 1px solid var(--sidebar-bg);
-    color: var(--fg) !important;
-    display: block;
-    padding: 2px;
-    margin: 8px 0 8px 12px;
-    text-align: left;
-    text-decoration: underline;
-    text-decoration-color: hsl(0, 0%, 0%, 0.1);
-  }
-  .pagetoc a:hover {
-    text-decoration-color: hsl(0, 0%, 0%, 0.5);
-  }
-  .pagetoc a.active {
-    background-color: var(--sidebar-active-bg);
-    color: var(--sidebar-active) !important;
-    text-decoration-color: hsl(219, 93%, 42%, 0.1);
-  }
-  .pagetoc a.active:hover {
-    text-decoration-color: hsl(219, 93%, 42%, 0.8);
-  }
-  .pagetoc .active {
-    background: var(--sidebar-bg);
-    color: var(--sidebar-fg);
-  }
-  .pagetoc .pagetoc-H1 {
+@media only screen and (max-width: 1020px) {
+  .toc-container {
     display: none;
   }
-  .pagetoc .pagetoc-H3 {
-    margin-left: 24px;
-  }
-  .pagetoc .pagetoc-H4 {
-    margin-left: 42px;
-  }
-  .pagetoc .pagetoc-H5 {
-    display: none;
-  }
-  .pagetoc .pagetoc-H6 {
-    display: none;
-  }
-  .toc-title {
-    margin: 0;
-    margin-bottom: 12px;
-    padding-left: 12px;
-    font-size: 1.4rem;
-    color: var(--full-contrast);
-  }
 }
diff --git a/docs/theme/page-toc.js b/docs/theme/page-toc.js
index 647a3810586b694582ac4a912b56092338324d2f..02996772db2ec90c1484f94952ed2a76b1d094fd 100644
--- a/docs/theme/page-toc.js
+++ b/docs/theme/page-toc.js
@@ -64,11 +64,15 @@ window.addEventListener("load", () => {
     (header) => !header.parentElement.tagName.toLowerCase().startsWith("h1"),
   );
   const sidetoc = document.querySelector(".sidetoc");
+  const tocContainer = document.querySelector(".toc-container");
 
   if (nonH1Headers.length === 0) {
     if (sidetoc) {
       sidetoc.style.display = "none";
     }
+    if (tocContainer) {
+      tocContainer.style.display = "none";
+    }
     return;
   }
 
diff --git a/docs/theme/plugins.js b/docs/theme/plugins.js
index 44c4c59978d31bd24ed0f0a28266868bb9951e51..18dd8ef9b8e70c6a2c082409e209aeb2837144a7 100644
--- a/docs/theme/plugins.js
+++ b/docs/theme/plugins.js
@@ -21,7 +21,6 @@ function detectOS() {
   return "Unknown";
 }
 
-// Usage
 var os = detectOS();
 console.log("Operating System:", os);
 
@@ -229,3 +228,124 @@ const copyMarkdown = () => {
 document.addEventListener("DOMContentLoaded", () => {
   copyMarkdown();
 });
+
+// Collapsible sidebar navigation for entire sections
+// Note: Initial collapsed state is applied in index.hbs to prevent flicker
+function initCollapsibleSidebar() {
+  var sidebar = document.getElementById("sidebar");
+  if (!sidebar) return;
+
+  var chapterList = sidebar.querySelector("ol.chapter");
+  if (!chapterList) return;
+
+  var partTitles = Array.from(chapterList.querySelectorAll("li.part-title"));
+
+  partTitles.forEach(function (partTitle) {
+    // Get all sibling elements that belong to this section
+    var sectionItems = getSectionItems(partTitle);
+
+    if (sectionItems.length > 0) {
+      setupCollapsibleSection(partTitle, sectionItems);
+    }
+  });
+}
+
+// Saves the list of collapsed section names to sessionStorage
+// This gets reset when the tab is closed and opened again
+function saveCollapsedSections() {
+  var collapsedSections = [];
+  var partTitles = document.querySelectorAll(
+    "#sidebar li.part-title.collapsible",
+  );
+
+  partTitles.forEach(function (partTitle) {
+    if (!partTitle.classList.contains("expanded")) {
+      collapsedSections.push(partTitle._sectionName);
+    }
+  });
+
+  try {
+    sessionStorage.setItem(
+      "sidebar-collapsed-sections",
+      JSON.stringify(collapsedSections),
+    );
+  } catch (e) {
+    // sessionStorage might not be available
+  }
+}
+
+function getSectionItems(partTitle) {
+  var items = [];
+  var sibling = partTitle.nextElementSibling;
+
+  while (sibling) {
+    // Stop when we hit another part-title
+    if (sibling.classList.contains("part-title")) {
+      break;
+    }
+    items.push(sibling);
+    sibling = sibling.nextElementSibling;
+  }
+
+  return items;
+}
+
+function setupCollapsibleSection(partTitle, sectionItems) {
+  partTitle.classList.add("collapsible");
+  partTitle.setAttribute("role", "button");
+  partTitle.setAttribute("tabindex", "0");
+  partTitle._sectionItems = sectionItems;
+
+  var isCurrentlyCollapsed = partTitle._isCollapsed;
+  if (isCurrentlyCollapsed) {
+    partTitle.setAttribute("aria-expanded", "false");
+  } else {
+    partTitle.classList.add("expanded");
+    partTitle.setAttribute("aria-expanded", "true");
+  }
+
+  partTitle.addEventListener("click", function (e) {
+    e.preventDefault();
+    toggleSection(partTitle);
+  });
+
+  // a11y: Add keyboard support (Enter and Space)
+  partTitle.addEventListener("keydown", function (e) {
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      toggleSection(partTitle);
+    }
+  });
+}
+
+function toggleSection(partTitle) {
+  var isExpanded = partTitle.classList.contains("expanded");
+  var sectionItems = partTitle._sectionItems;
+  var spacerAfter = partTitle._spacerAfter;
+
+  if (isExpanded) {
+    partTitle.classList.remove("expanded");
+    partTitle.setAttribute("aria-expanded", "false");
+    sectionItems.forEach(function (item) {
+      item.classList.add("section-hidden");
+    });
+    if (spacerAfter) {
+      spacerAfter.classList.add("section-hidden");
+    }
+  } else {
+    partTitle.classList.add("expanded");
+    partTitle.setAttribute("aria-expanded", "true");
+    sectionItems.forEach(function (item) {
+      item.classList.remove("section-hidden");
+    });
+    if (spacerAfter) {
+      spacerAfter.classList.remove("section-hidden");
+    }
+  }
+
+  saveCollapsedSections();
+}
+
+document.addEventListener("DOMContentLoaded", function () {
+  initCollapsibleSidebar();
+});