How the Reading Layout Works

Garden automates several layout details for long-form technical reading. Blog posts, column entries, and this handbook share the same stylesheets and measurement scripts.

1.Three-tier Adaptive Widths: 740px / 1040px / 1340px

An article page consists of a centered reading column and a floating right-hand table of contents (200px). On load and window resize, the ArticleMeasure script measures wide figures and tables in the body and expands them symmetrically into the available horizontal margins:

2.Two-line Title Splitting and Font Scaling

The ArticleTitle component applies two rules to headings:

1. With a delimiter (| with surrounding spaces): Splits the title into two lines at the first delimiter and computes the --l scaling variable from the wider line's character width (counting CJK characters as 1, uppercase letters as 0.68, other characters as 0.58, and spaces as 0.3) so the longer line fits without wrapping again. Screen readers still read the full title with the delimiter.
2. Without a delimiter: Renders a single <h1> with CSS text-wrap: balance, never splitting automatically on colons or dashes and never rescaling the font size.

Note

If a title includes a split delimiter with an empty left or right side, npx garden check emits a title-split warning requiring text on both sides of the delimiter.

3.Build-time Image Dimensions and Lightbox Zoom

When npx garden sync runs, the build script reads the pixel width and height of every local image (PNG, JPEG, WebP, GIF, and SVG) and writes them into the imageSizes map in .garden/generated-content.ts:

From build to the browser

Click a step to read what that stage does

Read sizes at build timeWrite width and height so text does not jump

The server HTML already carries width, height, and the wide-figure margins, so later text does not jump before the image loads.

Measure on the clientFit wide figures and the table of contents

After load, ArticleMeasure recomputes the margins for the current viewport and checks whether a wide figure covers the table of contents.

Dark backing and zoomA light pad behind dark lines, click to zoom

A click opens the lightbox on the same page. Dark mode puts a light paper color behind figures and does not invert them.

4.Dark-mode Image Backing and Warm Paper Tokens

Technical posts frequently include transparent-background architecture diagrams or equation screenshots drawn with dark lines. On a dark page background those dark lines disappear, while a CSS filter: invert distorts full-color screenshots.

In dark mode, Garden sets background: var(--image-backing) (#faf9f5) on article figures and lightbox images without applying color inversion or extra padding. Transparent dark-line diagrams stay legible, and opaque screenshots look unchanged. Site favicons share the same backing token, whereas post covers, avatars, and link card thumbnails do not.

The site palette is defined in app/styles/tokens.css without brand blue: