Skip to content

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.

  • 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.
  • 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.md in 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 to aria-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).
  • 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.
  • Deployed as static files to Cloudflare Pages (Cloudflare’s CDN; anycast, TLS 1.3, HTTP/2 and HTTP/3, Brotli at the edge).
  • A _headers file applies Chapter 6’s strategy: /_astro/* (hashed) gets public, max-age=31536000, immutable; the Pagefind index gets a short cache with stale-while-revalidate; HTML uses the platform’s default of revalidating on every request. Every response carries nosniff, a strict referrer policy, HSTS and a frame-ancestors 'none' CSP (Ch 13).
  • A generated sitemap-index.xml (Astro’s sitemap integration), a robots.txt pointing 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.
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 beforeprint handler opens every collapsible answer so quizzes and solutions appear in a saved PDF.

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.

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.