E. Colophon — How This Book Was Built
A book about the glue should be honest about its own glue. Here’s how this one is made, mapped to the chapters that explain each choice.
Build and rendering (Ch 1, 7)
Section titled “Build and rendering (Ch 1, 7)”- Astro with the Starlight documentation theme, authored in MDX. Every page is statically generated at build time (SSG): the HTML for all chapters exists before anyone asks for it, so the server does no rendering work per request.
- Islands, but lighter: interactive demos are tiny TypeScript custom elements, bundled by Astro only onto the pages that use them, and they do nothing until scrolled into view (an IntersectionObserver gate). No UI framework runtime ships to readers at all.
- The build emits content-hashed CSS and JS into
/_astro/, plus a Pagefind static search index — search runs entirely in the browser, loading index fragments on demand.
Diagrams (Ch 10, 15)
Section titled “Diagrams (Ch 10, 15)”- Every diagram is hand-authored inline SVG inside the MDX — no raster images of diagrams, no diagram library at runtime. They follow one visual language (see
DIAGRAM_STYLE.mdin the repository): processes are rounded rectangles, threads are lanes, storage is cylinders, the network is dashed, and the colours deliberately match the DevTools Performance panel (yellow scripting, purple rendering, green painting). - Colours are CSS custom properties that switch with the light/dark theme; arrowheads come from one shared
<defs>sprite per page. - Each SVG has a
<title>and<desc>wired toaria-labelledby(Ch 15’s canvas/SVG accessibility rule). Wide diagrams scroll horizontally inside a keyboard-focusable region instead of shrinking text on phones (Ch 15’s reflow rule).
Fonts, images and motion (Ch 18, 19)
Section titled “Fonts, images and motion (Ch 18, 19)”- No web fonts: system font stacks only. Zero font requests, zero font-swap layout shifts.
- The only raster image in the book (the author’s audit screenshot in Ch 16) goes through Astro’s image pipeline: resized, re-encoded to WebP at multiple widths with
srcset/sizes, and given explicit dimensions so it cannot cause layout shift. - Demos never animate on their own: motion starts only when the reader presses a button, stops when the demo scrolls out of view, and respects
prefers-reduced-motion.
Caching and delivery (Ch 5, 6)
Section titled “Caching and delivery (Ch 5, 6)”- Deployed as static files to Cloudflare Pages (Cloudflare’s CDN; anycast, TLS 1.3, HTTP/2 and HTTP/3, Brotli at the edge).
- A
_headersfile applies Chapter 6’s strategy:/_astro/*(hashed) getspublic, max-age=31536000, immutable; the Pagefind index gets a short cache withstale-while-revalidate; HTML uses the platform’s default of revalidating on every request. Every response carriesnosniff, a strict referrer policy, HSTS and aframe-ancestors 'none'CSP (Ch 13).
SEO plumbing (Ch 22)
Section titled “SEO plumbing (Ch 22)”- A generated
sitemap-index.xml(Astro’s sitemap integration), arobots.txtpointing to it, canonical URLs and per-page titles and descriptions from Starlight, Open Graph tags with a 1200×630 share image, a favicon, and a custom 404 page.
Print (Ch 18’s “the user’s context”)
Section titled “Print (Ch 18’s “the user’s context”)”- A print stylesheet hides navigation and interactive controls, prints link URLs, avoids breaking figures across pages, and a
beforeprinthandler opens every collapsible answer so quizzes and solutions appear in a saved PDF.
What was and wasn’t measured
Section titled “What was and wasn’t measured”This edition was produced under a deadline as a conceptual explainer. In the interest of honesty — the book’s own Chapter 16 would insist on it:
- Lighthouse scores were not recorded for this edition, and no automated accessibility (axe) or link-check pass was run. The architecture (static HTML, no web fonts, no framework runtime, lazy demos, hashed and immutable assets, reserved image dimensions) is the architecture this book recommends for good Core Web Vitals and CLS 0; verifying it with field data is left as the reader’s first exercise below.
- Facts: the text was written primarily from the author’s knowledge. Mechanisms and principles are stated carefully; incident stories are told for their lessons with approximate figures; browser-support statements for fast-moving APIs should be checked against MDN, caniuse or Baseline before you rely on a version number.
- Code: snippets are short and illustrative. The interactive demos run in the book itself; other snippets were not executed in a test harness.
Exercise: audit this book
Section titled “Exercise: audit this book”Run PageSpeed Insights on any chapter URL, record a Performance trace of Chapter 10 with 4× CPU throttling while scrolling past its demos, and check the response headers of an /_astro/ file and of an HTML page in DevTools. Then judge this book by its own lessons — and file an issue if it fails them.