From 1dc0a523dec2467200e75405d8f0df69bdd1939f Mon Sep 17 00:00:00 2001
From: Dhruv Manilawala <dhruvmanila@gmail.com>
Date: Thu, 5 Sep 2024 16:08:53 +0530
Subject: [PATCH] Separate TOC from the navigation

---
 docs/stylesheets/extra.css | 13 +++++++++++++
 mkdocs.template.yml        | 23 ++++++++++++++++-------
 scripts/generate_mkdocs.py | 36 ++++++++++++++++++++++++++++--------
 3 files changed, 57 insertions(+), 15 deletions(-)

diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index b3c35723d8..7f3886ca3e 100644
--- a/docs/stylesheets/extra.css
+++ b/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 ;
+  }
+}
diff --git a/mkdocs.template.yml b/mkdocs.template.yml
index 359971d51e..927bfccd32 100644
--- a/mkdocs.template.yml
+++ b/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
diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py
index 91a7302c9b..497ec60f08 100644
--- a/scripts/generate_mkdocs.py
+++ b/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