feat: mdBook site (Rust-book-style) with brand fonts + Cloudflare Pages config#13
Merged
Conversation
Replaces the hand-rolled static index.html with a proper mdBook site
built from the existing top-level Markdown chapters. The top-level
files stay canonical; scripts/build.sh syncs them into src/ before
mdbook compiles the site.
Brand styling per product.md:
- Surfaces: light = bone palette (#F2EAD8 on #0E0A05), dark = void
palette (#050505 surface, #ECE3CC text), navy preset selected as
the dark theme so mdBook picks it automatically.
- Accent: ember (#E8462E in light, #FF6A3D in dark) on links, active
sidebar items, selection background, and the in-page focus rule.
- Typography: Fraunces for display headings (variable opsz/SOFT/WONK
axes), Geist for body text and tables, JetBrains Mono for code
and SUMMARY part titles. All three load from Google Fonts via
theme/head.hbs with preconnect + display=swap.
- Readable scale: 16.5px body / 1.65 line-height / 72ch max line
length on paragraphs. Headings tighten the line-height and use a
subtle border-bottom on h2 so they read as section dividers
without shouting.
Files:
- book.toml mdBook config, additional CSS, edit URL pattern
- src/SUMMARY.md four-part chapter order (Getting started,
Architecture, Reference, Project)
- theme/head.hbs Google Fonts preconnect + link, meta theme-color
- theme/css/variables.css palette overrides for .light and .navy
- theme/css/typography.css font families, scale, blockquote, tables
- scripts/build.sh syncs top-level → src/, fetches mdbook if
missing, builds, copies _headers/_redirects
into book/
- _headers CSP with Google Fonts allow, HSTS, frame-deny,
cache rules
- _redirects friendly aliases (/architecture, /api, ...) +
legacy SETUP_GUIDE redirect to QUICKSTART
- DEPLOY_CLOUDFLARE.md deployment reference: settings, troubleshooting
Removed:
- index.html (the legacy single-page site). The mdBook output
replaces it.
Confirmed locally:
- Cold build from clean checkout: 11 chapters synced, mdbook
compiles, _headers and _redirects copied into book/.
- book/index.html carries the Google Fonts link and references
both fingerprinted theme CSS files.
Earlier theme leaned editorial-brutalism per product.md: warm bone cream surfaces, Fraunces for every heading, h2 with a border-bottom. That overpowered the prose in a reference-doc context. This pass takes the visual cues from doc.rust-lang.org/stable/book/ while keeping the brand fonts. Light theme is now near-white (hsl(0,0%,100%) bg, hsl(0,0%,12%) fg) with a calm gray sidebar (#fafafa) and a darker ember accent (#c93a25) that holds AA contrast on white. Dark theme stays on the void palette with the brighter #ff6a3d ember for AA on near-black. Typography drops Fraunces from every heading and keeps it only for H1 and the menu title. H2 through H6 use Geist. The h2 border-bottom is gone. Sizes tighten: H1 2.8rem, H2 2.0rem, H3 1.7rem. Body stays on Geist at 1.6rem / 1.6 line-height to match Rust-book density. Content max-width bumped to 820px (Rust book uses 750px; we go wider because the API reference tables are denser). Sidebar width 290px. Tables, code, blockquote, hr, and inline-code chips all get the calmer treatment: subtle borders, neutral backgrounds, no decorative strokes. Active sidebar item is a thin ember rule on the left rather than a coloured background. Verified: cold build is clean, both CSS files emit with a new fingerprint, fonts.googleapis.com link still present in head.
This was referenced May 23, 2026
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
Replaces the hand-rolled
index.htmlwith a proper mdBook site, themed to feel like doc.rust-lang.org/stable/book/ (clean reference doc, sans-serif body and headings, calm color palette) while preserving the Vyrox brand fonts and ember accent.What's new
mdBook scaffold (
book.toml,src/SUMMARY.md,scripts/build.sh)scripts/build.shsyncs them intosrc/before invokingmdbook build, so editing the top-level file is the only place a contributor needs to touch.src/*.mdare gitignored (regenerated by build); onlySUMMARY.mdis tracked insrc/.Brand theme (
theme/head.hbs,theme/css/variables.css,theme/css/typography.css)theme/head.hbswith preconnect anddisplay=swap: Fraunces, Geist, JetBrains Mono.#c93a25light /#ff6a3ddark) for links and active sidebar items, with AA contrast on both surfaces.Cloudflare Pages wiring (
_headers,_redirects,DEPLOY_CLOUDFLARE.md)_headerswith CSP that allows Google Fonts, HSTS, frame-deny, cache rules._redirectsmaps friendly aliases (/architecture,/api, etc.) to the mdBook chapter URLs.DEPLOY_CLOUDFLARE.mddocuments the exact project settings.Removed
index.html(the legacy single-page site). The mdBook output replaces it.Cloudflare Pages settings
mainbash scripts/build.shbookMDBOOK_VERSION=v0.4.40Verified locally
mdbookfetched and run,_headersand_redirectscopied intobook/.book/index.htmlcarries the Google Fonts link and references both fingerprinted theme CSS files.Test plan
bash scripts/build.sh, openbook/index.htmland confirm the look matches the Rust-book reference-doc feel