fix(deploy): land mdBook v0.5.3 bump + brand.css rename onto main#16
Merged
Conversation
Three deploy bugs the first Cloudflare render exposed: 1. Sidebar rendered ~30px wide with chapter titles wrapping after each character. Cause: scripts/build.sh pinned v0.4.40, but every CSS override in theme/css/ targets v0.5-only selectors (#mdbook-sidebar, #mdbook-sidebar-toggle-anchor, the nav-wide-wrapper layout). v0.4.x uses a different chrome DOM so our overrides did not match. Result: default sidebar width collapsed because :root --sidebar-target-width was set against v0.5 expectations. 2. GitHub icon missing from the top-right menu bar. v0.4 silently drops the `fab-github` icon name; v0.5 accepts it and renders the Font Awesome SVG. 3. README.md on main still had two H1s: "# Vyrox Security" then "# Your AI Security Copilot" with the project tagline gone. The fixup commit on docs/senior-rewrite-foundation was force- pushed AFTER PR #8 merged, so the merge landed the broken version. Apply the same fixup directly on this branch so the site renders one H1 plus the blockquote tagline. Changes: - scripts/build.sh: MDBOOK_VERSION default bumped v0.4.40 → v0.5.3. Matches the version we tested with locally. v0.5.3 binary is on GitHub releases (confirmed via curl); the existing tarball URL pattern resolves without change. - DEPLOY_CLOUDFLARE.md: env var table updated to v0.5.3. - README.md: drop the second "Your AI Security Copilot" H1 and restore the AI-security-copilot tagline as a blockquote. Verified locally with mdbook v0.5.3: - <html class="navy sidebar-visible"> on every page - <nav id="mdbook-sidebar"> present so CSS overrides apply - GitHub icon SVG rendered next to print + edit icons - README has exactly one H1
…k'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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings the two unmerged fix commits onto
mainso the production Cloudflare Pages deploy actually picks them up.When PR #13 and #14 merged earlier, they merged an EARLIER snapshot of
feat/mdbook-sitethat did not yet contain these two commits. Somainwas missing the actual fixes and the production deploy atvyrox-docs.pages.devwas still showing the broken layout (both arrows on the same side, sidebar collapsed). Every push since has only triggered preview deploys because the fix commits stayed onfeat/mdbook-site, not main.What's in this PR
Two commits, cherry-picked from
feat/mdbook-site:b315f81fix(build): pin mdBook to v0.5.3 + remove duplicate README headingscripts/build.sh: defaultMDBOOK_VERSIONv0.4.40→v0.5.3. v0.4 uses different chrome DOM selectors (.sidebarvs#mdbook-sidebar, no#mdbook-sidebar-toggle-anchor), so the CSS overrides we wrote against v0.5 silently did nothing on v0.4.DEPLOY_CLOUDFLARE.md: same version update in the docs table.README.md: drop the duplicate# Your AI Security CopilotH1 left behind by the foundation-rewrite merge, restore the project tagline blockquote.d70d90ffix(theme): rename variables.css -> brand.css to stop replacing mdBook's bundled varstheme/css/variables.css→theme/css/brand.cssbook.tomladditional-cssupdated to point at the new namebook.tomlexplaining the rule so a future contributor does not repeat the collisionWhy the rename matters
mdBook's theme override mechanism is full-file replacement, not a cascade. Any file dropped into
theme/css/whose name matches one of mdBook's bundled theme files (variables.css,general.css,chrome.css,print.css) replaces the bundled file outright.Our
theme/css/variables.csscollided with mdBook's bundledtheme/css/variables.css. mdBook used ours instead of its own, wiping out every default variable the layout depends on:--page-padding(the.nextarrow rule depends on it)--sidebar-width: min(var(--sidebar-target-width), 80vw)(the formula that sizes the sidebar)--sidebar-resize-indicator-width,--menu-bar-height, othersThat broke:
.next { right: var(--page-padding) }rule resolved toright: auto).Renaming the override file to
brand.csslets mdBook keep its ownvariables.cssin the cascade and stacks our overrides on top.After this merges to main
Cloudflare Pages production build kicks off on push to
main. Once it completes (about 90 seconds for the cold mdBook download + build),vyrox-docs.pages.devshould show:Test plan
vyrox-docs.pages.dev(force a hard refresh with Cmd+Shift+R / Ctrl+F5 to skip the cached build)