From ea952bdb4f185b920350966aa80f462e1b5e9ae8 Mon Sep 17 00:00:00 2001
From: Branimir Georgiev <braboj@gmail.com>
Date: Sat, 25 Apr 2026 18:30:33 +0300
Subject: [PATCH] feat: add playbook sidebar nav and fix theme FOUC

Add a grouped recipe navigation sidebar on the right for playbook
pages, replacing the tutorial links. Non-playbook pages keep
tutorial links. All pages keep the heading ToC on the left.

Fix flash of unstyled content by moving theme initialization from
the body to the head.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 astro-site/src/components/Header.astro      |  3 +-
 astro-site/src/components/PlaybookNav.astro | 81 +++++++++++++++++++++
 astro-site/src/layouts/DocLayout.astro      | 18 ++++-
 astro-site/src/pages/[...slug].astro        |  1 +
 astro-site/src/styles/global.css            | 76 ++++++++++++++++++-
 5 files changed, 173 insertions(+), 6 deletions(-)
 create mode 100644 astro-site/src/components/PlaybookNav.astro

diff --git a/astro-site/src/components/Header.astro b/astro-site/src/components/Header.astro
index cb4b7a1..261f14a 100644
--- a/astro-site/src/components/Header.astro
+++ b/astro-site/src/components/Header.astro
@@ -57,8 +57,7 @@ const base = import.meta.env.BASE_URL;
 
 <script is:inline>
   const toggle = document.getElementById("theme-toggle");
-  const saved = localStorage.getItem("theme") || "light";
-  document.documentElement.setAttribute("data-theme", saved);
+  const saved = document.documentElement.getAttribute("data-theme") || "light";
   updateToggleLabel(saved);
 
   toggle.addEventListener("click", () => {
diff --git a/astro-site/src/components/PlaybookNav.astro b/astro-site/src/components/PlaybookNav.astro
new file mode 100644
index 0000000..6b8b15e
--- /dev/null
+++ b/astro-site/src/components/PlaybookNav.astro
@@ -0,0 +1,81 @@
+---
+interface Recipe {
+  slug: string;
+  title: string;
+}
+
+interface Props {
+  currentSection: string;
+}
+
+const { currentSection } = Astro.props;
+const base = import.meta.env.BASE_URL;
+
+const groups: { label: string; recipes: Recipe[] }[] = [
+  {
+    label: "Everyday",
+    recipes: [
+      { slug: "playbook/undoing-changes", title: "Undoing Changes" },
+      { slug: "playbook/diffing", title: "Diffing" },
+      { slug: "playbook/history", title: "History" },
+      { slug: "playbook/stashing", title: "Stashing" },
+    ],
+  },
+  {
+    label: "Branching and Merging",
+    recipes: [
+      { slug: "playbook/branching", title: "Branching" },
+      { slug: "playbook/merging", title: "Merging" },
+      { slug: "playbook/rebasing", title: "Rebasing" },
+      { slug: "playbook/cherry-picking", title: "Cherry-Picking" },
+    ],
+  },
+  {
+    label: "Remote",
+    recipes: [
+      { slug: "playbook/remote-operations", title: "Remote Operations" },
+      { slug: "playbook/remote-management", title: "Remote Management" },
+    ],
+  },
+  {
+    label: "Project Structure",
+    recipes: [
+      { slug: "playbook/tagging", title: "Tagging" },
+      { slug: "playbook/submodules", title: "Submodules" },
+      { slug: "playbook/subtrees", title: "Subtrees" },
+    ],
+  },
+  {
+    label: "Advanced",
+    recipes: [
+      { slug: "playbook/selectors", title: "Selectors" },
+      { slug: "playbook/hooks", title: "Hooks" },
+      { slug: "playbook/debugging", title: "Debugging" },
+      { slug: "playbook/configuration", title: "Configuration" },
+    ],
+  },
+];
+---
+
+<nav class="playbook-nav">
+  <div class="playbook-nav-title">
+    <a href={`${base}playbook/`} class={currentSection === "playbook" ? "active" : ""}>Playbook</a>
+  </div>
+  {groups.map((group) => (
+    <div class="playbook-nav-group">
+      <div class="playbook-nav-group-label">{group.label}</div>
+      <ul>
+        {group.recipes.map((r) => (
+          <li>
+            <a
+              href={`${base}${r.slug}/`}
+              class={currentSection === r.slug ? "active" : ""}
+            >
+              {r.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  ))}
+</nav>
diff --git a/astro-site/src/layouts/DocLayout.astro b/astro-site/src/layouts/DocLayout.astro
index 50c10ae..8b9d5c8 100644
--- a/astro-site/src/layouts/DocLayout.astro
+++ b/astro-site/src/layouts/DocLayout.astro
@@ -2,6 +2,7 @@
 import "../styles/global.css";
 import Header from "../components/Header.astro";
 import TableOfContents from "../components/TableOfContents.astro";
+import PlaybookNav from "../components/PlaybookNav.astro";
 import TutorialLinks from "../components/TutorialLinks.astro";
 import Footer from "../components/Footer.astro";
 import site from "../data/site.json";
@@ -11,10 +12,12 @@ interface Props {
   description?: string;
   headings?: { depth: number; slug: string; text: string }[];
   currentPath?: string;
+  currentSection?: string;
   jsonLd?: Record<string, unknown>;
 }
 
-const { title, description, headings = [], currentPath = "/", jsonLd } = Astro.props;
+const { title, description, headings = [], currentPath = "/", currentSection = "", jsonLd } = Astro.props;
+const isPlaybook = currentSection === "playbook" || currentSection.startsWith("playbook/");
 const pageDescription = description || site.description;
 const pageTitle = `${title} — ${site.title}`;
 const canonicalUrl = new URL(Astro.url.pathname, Astro.site);
@@ -54,6 +57,13 @@ const ogImage = new URL("/tutorial-git/images/og-banner.png", Astro.site);
     {jsonLd && (
       <script type="application/ld+json" set:html={JSON.stringify(jsonLd)} />
     )}
+
+    <script is:inline>
+      document.documentElement.setAttribute(
+        "data-theme",
+        localStorage.getItem("theme") || "light"
+      );
+    </script>
   </head>
   <body>
     <a href="#main-content" class="skip-link">Skip to main content</a>
@@ -64,7 +74,11 @@ const ogImage = new URL("/tutorial-git/images/og-banner.png", Astro.site);
         <h1>{title}</h1>
         <slot />
       </main>
-      <TutorialLinks />
+      {isPlaybook ? (
+        <PlaybookNav currentSection={currentSection} />
+      ) : (
+        <TutorialLinks />
+      )}
     </div>
     <Footer />
   </body>
diff --git a/astro-site/src/pages/[...slug].astro b/astro-site/src/pages/[...slug].astro
index f38997b..bb976de 100644
--- a/astro-site/src/pages/[...slug].astro
+++ b/astro-site/src/pages/[...slug].astro
@@ -47,6 +47,7 @@ const jsonLd = {
   description={entry.data.description}
   headings={headings}
   currentPath={sectionPath}
+  currentSection={page.section}
   jsonLd={jsonLd}
 >
   <Content />
diff --git a/astro-site/src/styles/global.css b/astro-site/src/styles/global.css
index 950b7a7..6cf30ba 100644
--- a/astro-site/src/styles/global.css
+++ b/astro-site/src/styles/global.css
@@ -29,7 +29,7 @@
   --space-2xl: 3rem;
 
   /* Sizing */
-  --sidebar-width: 12rem;
+  --sidebar-width: 16rem;
   --header-height: 3rem;
   --tab-height: 2.5rem;
   --max-content: 50rem;
@@ -382,6 +382,77 @@ a:hover {
   content: "−";
 }
 
+/* Right sidebar — Playbook navigation */
+.playbook-nav {
+  position: sticky;
+  top: calc(var(--header-height) + var(--tab-height));
+  height: calc(100vh - var(--header-height) - var(--tab-height));
+  overflow-y: auto;
+  padding: var(--space-lg) var(--space-md);
+  border-left: 1px solid var(--color-border);
+  font-size: var(--font-size-sm);
+}
+
+.playbook-nav-title {
+  font-size: var(--font-size-sm);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: var(--space-md);
+}
+
+.playbook-nav-title a {
+  color: var(--color-fg-muted);
+}
+
+.playbook-nav-title a:hover,
+.playbook-nav-title a.active {
+  color: var(--color-primary-light);
+  text-decoration: none;
+}
+
+.playbook-nav-group {
+  margin-bottom: var(--space-md);
+}
+
+.playbook-nav-group-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--color-fg-faint);
+  margin-bottom: var(--space-xs);
+}
+
+.playbook-nav ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.playbook-nav li {
+  margin-bottom: 1px;
+}
+
+.playbook-nav li a {
+  display: block;
+  color: var(--color-fg-muted);
+  padding: var(--space-xs) var(--space-sm);
+  border-radius: 3px;
+}
+
+.playbook-nav li a:hover {
+  color: var(--color-primary-light);
+  background: var(--color-bg-hover);
+  text-decoration: none;
+}
+
+.playbook-nav li a.active {
+  color: var(--color-primary);
+  background: var(--color-bg-alt);
+  font-weight: 500;
+}
+
 /* Content area */
 .content {
   padding: var(--space-xl) var(--space-2xl);
@@ -560,7 +631,8 @@ a:hover {
   }
 
   .sidebar-toc,
-  .sidebar-tutorials {
+  .sidebar-tutorials,
+  .playbook-nav {
     display: none;
   }
 }