From 8b0787b81b0feafde4b335d79351f51a200bb299 Mon Sep 17 00:00:00 2001
From: keirsalterego <darksalterego99@gmail.com>
Date: Sun, 24 May 2026 00:25:56 +0530
Subject: [PATCH] fix(theme): rename variables.css -> brand.css to stop
 replacing mdBook's bundled vars

The actual cause of the broken sidebar and the both-arrows-on-the-
same-side bug was not the mdBook version. It was a file-name
collision.

mdBook treats any file in `theme/css/` whose name matches one of
its bundled theme files (variables.css, general.css, chrome.css,
print.css) as a FULL REPLACEMENT for the bundled file, not as an
override that cascades on top. Our `theme/css/variables.css` had
the same name as mdBook's bundled `theme/css/variables.css`, so
mdBook used our file instead of its own. Our file only contained
the dark-palette overrides; every other mdBook variable
(`--page-padding`, `--sidebar-width`, `--sidebar-resize-indicator-width`,
`--menu-bar-height`, etc) was wiped out.

The visible consequences:

1. `.next { right: var(--page-padding) }` resolved to
   `right: auto` because the var no longer existed. Both
   `.previous` and `.next` fell back to the same default position,
   producing the screenshot where both chapter arrows sat on the
   right edge.
2. The sidebar width calculation `min(var(--sidebar-target-width),
   80vw)` had no `--sidebar-width` aggregator to consume it, so
   the sidebar collapsed to its content-min-width (about 30px),
   wrapping each chapter title one character per line.
3. The chrome's resize-handle positioning relied on
   `--sidebar-resize-indicator-width`, which was also gone.

Fix: rename `theme/css/variables.css` to `theme/css/brand.css`. No
mdBook bundled file uses that name, so mdBook keeps its own
variables.css in the cascade and adds ours on top via
`additional-css`. Verified locally:

  - book/css/variables-*.css (mdBook's) now defines --page-padding,
    --sidebar-target-width: 300px (mdBook default), --sidebar-width
    formula, --menu-bar-height, etc.
  - book/theme/css/brand-*.css (ours) overrides --sidebar-target-width
    to 290px and the colour palette.
  - The two files no longer have identical content (they had
    matching md5 in the broken build because mdBook was using our
    file as both the bundled file AND the additional file).
  - The `.next { right: var(--page-padding) }` rule now resolves to
    a real 15px and our `nav.nav-wide-wrapper a.nav-chapters.previous
    { left: var(--page-padding) }` rule wins specificity and pins the
    previous arrow to the left edge.

Also documented the rule in book.toml so a future contributor does
not repeat the mistake.
---
 book.toml                              | 11 ++++++++++-
 theme/css/{variables.css => brand.css} |  0
 2 files changed, 10 insertions(+), 1 deletion(-)
 rename theme/css/{variables.css => brand.css} (100%)

diff --git a/book.toml b/book.toml
index ae822b1..919f97a 100644
--- a/book.toml
+++ b/book.toml
@@ -34,7 +34,16 @@ preferred-dark-theme = "navy"
 # copy-paste. Leaving curly-quotes on for prose readability.
 smart-punctuation = false
 
-additional-css = ["theme/css/variables.css", "theme/css/typography.css"]
+# Critical: do NOT name override files after mdBook's own bundled
+# theme files (variables.css, general.css, chrome.css, print.css).
+# mdBook treats any file in `theme/css/` whose name matches a
+# bundled file as a full replacement, which wipes out the standard
+# variables like `--page-padding` and `--sidebar-resize-indicator-width`.
+# That broke the chapter-nav arrow positioning and the sidebar width
+# in the first deploy. We use `brand.css` for the palette overrides
+# instead, and add it as additional-css so it cascades on top of the
+# defaults.
+additional-css = ["theme/css/brand.css", "theme/css/typography.css"]
 additional-js = []
 
 # Edit-this-page link on every chapter. Points at the top-level file
diff --git a/theme/css/variables.css b/theme/css/brand.css
similarity index 100%
rename from theme/css/variables.css
rename to theme/css/brand.css