Skip to content

fix(theme): permanent dark mode + sidebar always open + arrows on edges #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
keirsalterego merged 1 commit into from
May 23, 2026
Merged

fix(theme): permanent dark mode + sidebar always open + arrows on edges #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions book.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,13 @@ build-dir = "book"
create-missing = false

[output.html]
# Use the brand colour for the in-page accent and the website meta tags.
# Light theme is the daylight reading mode (bone palette). Dark theme
# is the void palette. Both are styled by theme/css/variables.css.
default-theme = "light"
# Vyrox docs are dark-only. The brand spec calls for the void / pitch
# surface and customers reading at 2am should not be flashed with
# white. We set both the default theme and the preferred-dark theme
# to "navy" (our void-palette override) and our variables.css makes
# every other built-in theme name fall through to the same dark
# colour set so a user who picks a different theme still sees dark.
default-theme = "navy"
preferred-dark-theme = "navy"

# Smarter punctuation handling. mdBook would otherwise turn the "--"
Expand Down
75 changes: 75 additions & 0 deletions theme/css/typography.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,3 +261,78 @@ pre {
.content h4 { font-size: 1.25rem; }
.content table { font-size: 1.35rem; }
}

/* -------------------------------------------------------------------
* Layout fixes for the chapter-arrow nav.
*
* mdBook's default chrome hides the wide previous/next arrows when
* the sidebar is open AND the viewport is narrower than 1380px. That
* leaves only the mobile inline arrows at the bottom of the page,
* which is what someone in the middle viewport band actually sees.
* The fix: keep the wide arrows visible across the full sidebar-open
* range so the layout reads as "sidebar on the left, content in the
* middle, arrows on the edges". Overrides go in this file because we
* load it after mdBook's chrome.css.
* ------------------------------------------------------------------- */
@media only screen and (max-width: 1380px) {
/* When the sidebar is open, do NOT swap to mobile-style nav.
Keep the wide arrows on the left and right edges. */
#mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper {
display: block;
}
#mdbook-sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper {
display: none;
}
}

/* -------------------------------------------------------------------
* Explicit arrow positioning. mdBook's chrome already puts
* `.previous { float: left }` and `.next { float: right }`, but a
* couple of `[dir=rtl]` and specificity edge cases can flip them on
* some viewports. We pin the positions with higher-specificity rules
* that ignore direction since the docs are LTR.
* ------------------------------------------------------------------- */
nav.nav-wide-wrapper a.nav-chapters.previous {
left: var(--page-padding);
right: auto;
float: left;
}

nav.nav-wide-wrapper a.nav-chapters.next {
right: var(--page-padding);
left: auto;
float: right;
}

/* The mobile nav stays as a fallback for viewports under 1080px. We
only show it when there is genuinely no room for the wide arrows. */
@media only screen and (max-width: 1080px) {
.nav-wide-wrapper { display: none !important; }
.nav-wrapper { display: block !important; }
}

/* -------------------------------------------------------------------
* Sidebar default-visible safety net.
*
* head.hbs pre-sets the localStorage key, but on the very first paint
* before JS runs we want the sidebar visible on any viewport wide
* enough to support the side-by-side layout. mdBook's default applies
* `sidebar-visible` to <html> based on width; we re-assert here so a
* CSS-only client (or one with JS disabled) still sees the chapters.
* ------------------------------------------------------------------- */
@media only screen and (min-width: 1080px) {
html:not(.js) .sidebar { transform: none !important; }
html:not(.js) .page-wrapper {
margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)) !important;
}
}

/* -------------------------------------------------------------------
* Paint the dark background before any stylesheet that follows can
* override it. Belt-and-braces against a flash of white if our
* variables.css loads later than expected on a cold browser cache.
* ------------------------------------------------------------------- */
html, body {
background-color: #0a0a0b !important;
color: #ece3cc;
}
117 changes: 42 additions & 75 deletions theme/css/variables.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,80 +1,45 @@
/*
* Vyrox docs theme variables.
*
* The target visual is a clean reference doc in the style of the Rust
* book (https://doc.rust-lang.org/stable/book/). Plain near-white
* background, high-contrast text, a single accent colour for links
* and active sidebar items, no decorative borders.
* Dark-only by design. The brand surface is "void" and the docs are
* read in operator contexts where a white page is the wrong choice.
* Every built-in mdBook theme class (.light, .navy, .coal, .ayu, .rust)
* resolves to the same dark colour set so a stale localStorage
* preference cannot flash a light page.
*
* The brand still shows up through the ember accent and the heading
* face, but it does not fight the prose.
*
* mdBook ships several built-in themes. We override only the
* variables we need; everything else falls through to the upstream
* defaults.
* The palette comes from product.md:
* void #050505 page background
* pitch #0A0A0B raised surface
* graphite #14141A sidebar surface
* ash #1F1F26 borders, rules
* bone #ECE3CC primary text on void
* clay #6B5E48 muted text on void
* marrow #FFE6B0 inline code colour
* ember #E8462E primary accent
* ember-2 #FF6A3D active links, active sidebar
* ember-3 #FF9156 link colour, brighter for AA contrast
* rust #8B2A12 search-highlight background
*/

:root {
/* Slightly wider than mdBook's default to fit the longer tables
in the API reference without horizontal scroll. The Rust book
uses 750px; we go to 820px because our API tables are wider. */
--content-max-width: 820px;
--sidebar-target-width: 290px;
}

/* -------------------------------------------------------------------
* Light theme. The default and the recommended reading experience.
* Near-white background, near-black text, ember accent.
* ------------------------------------------------------------------- */
.light, html:not(.js) {
--bg: hsl(0, 0%, 100%);
--fg: hsl(0, 0%, 12%);

--sidebar-bg: #fafafa;
--sidebar-fg: hsl(0, 0%, 12%);
--sidebar-non-existant: #aaa;
--sidebar-active: #c93a25;
--sidebar-spacer: #f0f0f0;

--scrollbar: #8f8f8f;

--icons: #747474;
--icons-hover: #c93a25;

--links: #c93a25;
--inline-code-color: #6b1a08;

--theme-popup-bg: #fafafa;
--theme-popup-border: #d8d8d8;
--theme-hover: #ececec;

--quote-bg: #f6f6f6;
--quote-border: #e5e5e5;

--warning-border: #c9892f;

--table-border-color: hsl(0, 0%, 92%);
--table-header-bg: hsl(0, 0%, 96%);
--table-alternate-bg: hsl(0, 0%, 98%);

--searchbar-border-color: #cccccc;
--searchbar-bg: #ffffff;
--searchbar-fg: #0e0a05;
--searchbar-shadow-color: rgba(0, 0, 0, 0.08);
--searchresults-header-fg: #777;
--searchresults-border-color: #e5e5e5;
--searchresults-li-bg: #fafafa;
--search-mark-bg: #ffe6b0;

--color-scheme: light;
}

/* -------------------------------------------------------------------
* Dark theme (navy). Selected automatically for users whose OS
* prefers dark. Pitch black background, warm-cream text, brighter
* ember accent for AA contrast.
* ------------------------------------------------------------------- */
.navy {
/*
* Single declaration block applied to every theme name. mdBook switches
* the html class but every class resolves to the same values. We pin
* `color-scheme: dark` on :root too so browser-provided UI (scrollbars,
* form controls) match.
*/
:root,
html,
.light,
.rust,
.coal,
.navy,
.ayu,
html:not(.js) {
--bg: #0a0a0b;
--fg: #ece3cc;

Expand Down Expand Up @@ -117,15 +82,17 @@
--color-scheme: dark;
}

/* -------------------------------------------------------------------
* Selection colour. Subtle ember tint on light, slightly stronger on
* dark so the highlight reads through the lower-contrast surface.
* ------------------------------------------------------------------- */
.light ::selection {
background: rgba(232, 70, 46, 0.16);
color: #0e0a05;
}
.navy ::selection {
::selection {
background: rgba(255, 106, 61, 0.32);
color: #ece3cc;
}

/*
* Hide the theme picker entirely. Dark is the only mode; offering a
* choice that does nothing is worse than offering no choice.
*/
.icon-button#theme-toggle,
.icon-button[aria-controls="theme-list"],
#theme-list {
display: none !important;
}
36 changes: 23 additions & 13 deletions theme/head.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,35 @@
<!--
Custom <head> hook for the Vyrox docs site.

Loads the three brand typefaces (Fraunces, Geist, JetBrains Mono)
from Google Fonts with `display=swap` so the layout never blocks on
the font request, and preconnects to the font CDNs to shave the
initial-paint latency.

Fonts:
Fraunces Variable serif, used for headings. We request the
optical-size, soft, and wonk axes so the headings
can use the editorial italics from product.md.
Geist Body. Five weights (300, 400, 500, 600, 700).
JetBrains Mono Code. Four weights (400, 500, 600, 700).
Three jobs:

1. Pre-set the mdbook-theme and mdbook-sidebar localStorage keys
so a fresh visitor lands on dark theme with the sidebar open.
This runs synchronously before the page paints to avoid any
flash of the wrong state. Wrapped in try/catch because Safari
in private mode throws on localStorage writes.

2. Load the three brand typefaces (Fraunces, Geist, JetBrains
Mono) from Google Fonts with preconnect + display=swap.

3. Carry the brand meta tags (theme-color, color-scheme).
-->

<script>
try {
localStorage.setItem('mdbook-theme', 'navy');
if (!localStorage.getItem('mdbook-sidebar')) {
localStorage.setItem('mdbook-sidebar', 'visible');
}
} catch (e) { /* private mode or storage disabled — fall through */ }
</script>

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

<link rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght,SOFT,WONK@9..144,300..900,0..100,0..1&family=Geist:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap">

<meta name="theme-color" content="#050505">
<meta name="color-scheme" content="light dark">
<meta name="theme-color" content="#0a0a0b">
<meta name="color-scheme" content="dark">
<meta name="description" content="Vyrox Security engineering documentation. Architecture, API contracts, threat model, audit-log spec, EDR adapter guide.">
Loading