Separate TOC from the navigation

docs/stylesheets/extra.css

@@ -109,3 +109,16 @@
     user-select: none;
 }
 
+/* Omits the nav title "Ruff" entirely unless on a small screen, in which case
+the nav title is needed for backwards navigation in the collapsible
+nav variant.
+
+See https://github.com/astral-sh/uv/issues/5130 */
+.md-nav__title {
+  display: none;
+}
+@media screen and (max-width: 1219px) {
+  .md-nav__title {
+    display: flex ;
+  }
+}

mkdocs.template.yml

@@ -4,16 +4,16 @@ theme:
   logo: assets/bolt.svg
   favicon: assets/favicon.ico
   features:
-    - navigation.instant
-    - navigation.instant.prefetch
-    - navigation.tracking
     - content.code.annotate
-    - toc.integrate
-    - toc.follow
-    - navigation.path
-    - navigation.top
     - content.code.copy
     - content.tabs.link
+    - navigation.footer
+    - navigation.instant
+    - navigation.instant.prefetch
+    - navigation.path
+    - navigation.top
+    - navigation.tracking
+    - toc.follow
   palette:
     # Note: Using the system theme works with the insiders version
     # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#automatic-light-dark-mode
@@ -71,6 +71,15 @@ not_in_nav: |
 extra:
   analytics:
     provider: fathom
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/astral-sh/ruff
+    - icon: fontawesome/brands/discord
+      link: https://discord.com/invite/astral-sh
+    - icon: fontawesome/brands/python
+      link: https://pypi.org/project/ruff/
+    - icon: fontawesome/brands/x-twitter
+      link: https://x.com/astral_sh
 validation:
   omitted_files: warn
   absolute_links: warn

scripts/generate_mkdocs.py

@@ -28,8 +28,16 @@ class Section(NamedTuple):
 
 SECTIONS: list[Section] = [
     Section("Overview", "index.md", generated=True),
-    Section("Tutorial", "tutorial.md", generated=False),
-    Section("Installing Ruff", "installation.md", generated=False),
+    Section(
+        "Getting Started",
+        "",
+        generated=False,
+        subsections=[
+            Section("Tutorial", "tutorial.md", generated=False),
+            Section("Installation", "installation.md", generated=False),
+            Section("Configuration", "configuration.md", generated=False),
+        ],
+    ),
     Section("The Ruff Linter", "linter.md", generated=False),
     Section("The Ruff Formatter", "formatter.md", generated=False),
     Section(
@@ -44,11 +52,17 @@ SECTIONS: list[Section] = [
             Section("Migrating from ruff-lsp", "editors/migration.md", generated=False),
         ],
     ),
-    Section("Configuring Ruff", "configuration.md", generated=False),
-    Section("Preview", "preview.md", generated=False),
-    Section("Rules", "rules.md", generated=True),
-    Section("Settings", "settings.md", generated=True),
-    Section("Versioning", "versioning.md", generated=False),
+    Section(
+        "Reference",
+        "",
+        generated=False,
+        subsections=[
+            Section("Preview", "preview.md", generated=False),
+            Section("Rules", "rules.md", generated=True),
+            Section("Settings", "settings.md", generated=True),
+            Section("Versioning", "versioning.md", generated=False),
+        ],
+    ),
     Section("Integrations", "integrations.md", generated=False),
     Section("FAQ", "faq.md", generated=False),
     Section("Contributing", "contributing.md", generated=True),
@@ -125,8 +139,14 @@ def main() -> None:
 
     Path("docs").mkdir(parents=True, exist_ok=True)
 
+    section_queue = SECTIONS.copy()
+
     # Split the README.md into sections.
-    for title, filename, generated, _ in SECTIONS:
+    while section_queue:
+        title, filename, generated, sub_sections = section_queue.pop(0)
+        if sub_sections is not None:
+            section_queue.extend(sub_sections)
+
         if not generated:
             continue