Build write-up · 5 min read

How I built While We’re Here

A coffee-table book that started as talk on lake walks and ends as a press-ready PDF. It is made the way I make software: one source of truth, a build step, and guards that refuse to ship the wrong file. It is not a website.

Role
Everything: writing, design, production
Built with
Markdown, HTML and CSS, paginated by Vivliostyle; Node and Python tooling
Trim
300 × 300 mm hardcover
Status
Complete draft, not press-final
A mockup of the finished book: the square hardcover lying on a travertine coffee table in warm afternoon light, the title WHILE WE’RE HERE in tall black Didone capitals over the watercolor-and-drafting cover art, with a stoneware mug of tea, dried grasses and an olive tree nearby.

My approach

  1. 01Write

    • Talk on lake walks, with an AI asking questions back
    • Markdown with front matter, one file per essay
    • A facts file the build checks quotations and numbers against
    What AI actually did

  2. 02Design

    • 300 mm square, laid out in points against real press geometry
    • Trim, bleed, gutter and baseline grid in one config file
    • Of 174 pictures, 95 are my photographs. Every design call is mine
    What comes out of it

  3. 03Build

    • A Node script composes markdown into one HTML document
    • Vivliostyle paginates it with CSS paged media, straight to PDF
    • Press masters in Git LFS; Python for derivatives, fonts and PDF reads
    • AI wrote the build code to rules I set
    The production system

  4. 04Proof

    • Scripts walk in from every trim edge to prove the bleed
    • Image DPI, overflow, page breaks and contrast all checked
    • A Ghostscript preflight for PDF/X. AI runs the checks, I decide what ships
    Guards

The problem

I wanted to write essays about paying attention, and a website is a bad place to do that. A page you scroll is a page you skim. Every website is one tab away from whatever is competing for the attention the essays are about. A book cannot be tabbed away from. It also cannot be edited after it prints, which changes how carefully you write.

So the output had to be a physical object. How could I make one and keep what software does well? Version control, a build step, and a clear view of what changed.

HTML and CSS as the production system

The book is written in markdown, composed by a build script, and paginated by a browser engine that implements the paged-media parts of CSS.

Print geometry lives in one config file: trim, bleed, safe area, the gutter the binding swallows, margins, the baseline grid. Nothing printer-specific is hard-coded anywhere else.

A spread is a diff. A typographic change is one line, not an afternoon of manual reflow. When a printer sends a production template, the numbers change in one place.

  • Every page knows which side it is on, so facing spreads are paired rather than assumed
  • Screen-resolution derivatives build the web preview; the press masters never go near it
  • The press PDF carries bleed and crop marks; the reading PDF does not, and they are different scripts on purpose

What comes out of it

Finished spreads from the current press build, as the PDF paginates them.

An open spread: a dog asleep in a rectangle of afternoon light on a bare floor, overprinted with faint survey linework, facing a cream title page reading Most of Life Is a Tuesday.
The first essay opens on the quietest possible image, surveyed: a dog asleep in afternoon light, overprinted with the solar geometry that produced it.
An open spread: a close photograph of honeybees working a comb behind glass, facing a title page reading The Beauty of Systems Nobody Designed.
The Beauty of Systems Nobody Designed. A colony working behind glass.
An open spread with a sentence set at poster scale in heavy Didone type: the extraordinary becomes ordinary not because it stopped being extraordinary, but because we stopped noticing it.
Pull-quote spreads set one sentence at poster scale in the cover face.
An open spread on near-black pages: a photograph of a vaulted stone cistern, facing the part title The World Is Changing in cream serif type.
Part III runs on dark pages. The palette flips for the section set inside the change.
A dark spread carrying a single long sentence in cream Didone type: absence was not a setting selected from a menu, it was what happened when a body moved beyond the length of a wire.
The dark pages let a single sentence carry a whole spread.
An open spread: a photograph of a long boardwalk stair with the photographer’s shadow cast up it, facing a title page reading The Body Cannot Skip the Hill.
The Body Cannot Skip the Hill, from the part on pilgrimage. My shadow, my staircase.

A $500 quote, and four arguments made twice

A single copy came back quoted at $500. That number did what deadlines and taste had not: it forced a real edit.

The book was eight essays in four parts. Looking at it properly with the money in mind, I saw that the pairs were not eight ideas. They were four ideas approached twice:

  • What you notice is what your life is made of
  • Mind and order are distributed rather than located in you
  • We are inside a change we can only partly see
  • Presence is earned and temporary

So there are now two real editions, not a draft and a replacement. One is the eight-essay book. The other is a four-essay reading cut at roughly ninety pages. Neither supersedes the other until a printer decides it. The site publishes both.

Each build states which edition it is. It used to infer that from the page count, until the shorter book landed on exactly the threshold that test was using.

Building to a number that stopped being true

Every pacing decision was made against a 130-page ceiling, one printer’s hard maximum. Adding a spread meant removing one.

Then that printer was ruled out on price, and the ceiling went with it. The 130 pages stayed. The book was composed to them, and they are the only measured numbers the project has.

The config file says so. These numbers came from a printer who is no longer the printer, so every one is now a question. A brief is ready to ask four printers the same things.

That is the part I would show a client. A constraint you cannot verify is a guess wearing a number. The useful move is to label it, not quietly keep trusting it.

Guards, because print fails silently

Software tells you when it breaks. A press file does not. It looks fine on screen and goes wrong on a machine you are not standing next to, after you have paid. So the build refuses more than it reports.

  • The press script once ran the trimmed proof build behind a press-ready preflight and produced a file with no bleed at all. The build line now names what it is doing, and that is checked
  • Cutting the interior out of the press PDF refuses unless the first page carries the title and the last carries the back-cover line. Both are read from the content, so it cannot strip the outer pages on position alone
  • A separate check asks whether the published reading PDF is the current book. It is committed to the repository, so a stale one would ship on the next push
  • The preflight tool is checked for before a long build starts, since press-ready hangs rather than fails when it is missing

What AI actually did

The essays started as talk, on walks around the lakes, thinking out loud with an AI that asked questions back. Those conversations came home as raw material: too long, too loose, and not yet about anything.

After that, I decided which threads were worth pursuing, cut the rest, and shaped what survived into essays that argue something.

The honest line is not that I wrote it and AI helped. The thinking happened out loud, and the judgment about what was true and what stayed was mine at every step.

The pictures are more clear-cut. Of the 174 images, 95 are photographs I took and seventeen more are archive or original artwork. Fourteen are generated, and each is recorded as generated in the manifest that builds the credits page.

The rest of what AI earned was the production system: the build scripts, the pagination edge cases, the guards above. What changed there is how quickly a bad idea can be shown to be bad.

I would not call any of this a new way of writing. People have composed on walks for as long as they have walked. This time the walk answered back, and came home as a draft.

The remaining work is not code. These four jobs are written down as open questions, which is the only honest place for them:

  • Choose a printer
  • Get their paper caliper
  • Find out whether they want a specific PDF standard
  • Get consent from anyone identifiable if the book is ever sold