Maintaining and Updating Documents

In the long tail of any document project, the work is maintenance. The initial production — the typographic decisions, the layout, the project structure, the first PDF generation — occupies a defined and finite span of time. What follows is often longer: a report updated annually with new data, a book revised for a second edition, an academic paper corrected after publication, an institutional style guide that must be kept current as the institution evolves. The difference between a document project that ages well and one that becomes a source of dread is almost entirely determined by decisions made during the initial production: whether the content and presentation are cleanly separated, whether the CSS is legible, whether the project is structured so that the next person — or the future you — can find what they need and change it without breaking everything else.

This final chapter considers document maintenance not as an afterthought but as a design constraint that shapes every decision in the book. It asks what kinds of changes a document undergoes over its life, which changes should be easy and which are inherently complex, and how the work done in the preceding twenty-five chapters has specifically prepared you to handle each kind of change confidently.

· · ·

A taxonomy of document changes Knowing which kind you are making

Not all document changes are equal. Some changes touch only content — correcting a number, updating a name, adding a paragraph. Others touch only presentation — adjusting the type scale, changing the accent color, tightening the margins. Others touch the structural relationship between content and presentation — adding a new kind of element that requires new CSS, or restructuring sections in a way that changes how the page sequence is assembled. And some changes are systemic — updating Paged.js, changing the rendering tool, reformatting the document for a new trim size.

The distinction matters because each kind of change carries a different risk profile and a different scope of review. A content correction has a small scope: the corrected text and the surrounding paragraphs. A systemic change has the largest scope: the entire document must be reviewed for unintended consequences. Understanding which kind of change you are making before you make it determines how much testing the change requires and how careful you need to be.

The layered CSS structure from Chapter 25 is directly relevant here. Because each CSS concern lives in its own file, the scope of any change is bounded by its layer. A change to 01-tokens.css propagates everywhere but is easy to find and understand — it is a single value in a single file, with clear meaning. A change to 05-components.css affects every instance of the modified component but leaves the page geometry, typography, and token values untouched. The layers are not just an organisational convenience; they are a risk management tool that makes the scope of any change predictable before the change is made.

· · ·

Content changes without layout disruption The art of the small correction

The most common maintenance task for a published document is a content correction: a factual error discovered after distribution, a name updated to reflect a change in circumstance, a figure revised as new data arrives. Done well, a content correction is invisible — the document looks identical except for the corrected material. Done carelessly, it produces a visible ripple: the corrected paragraph now ends one line shorter than before, which pushes the following heading to the bottom of a page, which triggers a cascade of break changes through the rest of the section.

The discipline required is minimal but consistent. When making a text correction, first make the smallest change that corrects the error: avoid replacing a short phrase with a long one when a short one will do, and avoid adding explanatory material when the correction itself is sufficient. If the correction must change the line count — and some corrections legitimately must — review all pages from the correction point to the next structural break (the next chapter opener or section boundary) and verify that the break positions are still acceptable.

When adding new content — a new paragraph, a new figure, a new section — the same principle applies in a more extended form. Add the content, regenerate the document, and review everything from the insertion point to the end of the chapter. Pay specific attention to headings that may now be too close to a page bottom, figures that may have shifted to a less appropriate position, and the final page of the chapter, which may now have a different fill. Most additions require only a few minutes of review; a very few require adjusting a break control or repositioning a figure.

The most important tool for managing content changes safely is not a CSS property or a shell script — it is the habit of reviewing the full generated PDF before distribution, not just the changed pages. A change that seems local at the source level sometimes has surprising downstream effects, particularly in documents with tight break-inside: avoid constraints on large elements. The review does not need to be exhaustive for small changes; scanning through the document at a pace of three or four seconds per page is sufficient to catch most problems. The scan is not optional.

· · ·

Design updates via the cascade Changing everything by changing one thing

The most powerful maintenance feature of an HTML-CSS document system is the cascade: the ability to change a visual property everywhere it appears by changing the value in one place. Every design decision in this book has been built toward this capability — the custom properties in 01-tokens.css, the layered CSS structure, the consistent use of token references rather than hardcoded values throughout the stylesheet. The reward for that discipline arrives the first time you need to make a design update.

Suppose the organisation that commissioned the document has refreshed its brand and the accent color has changed from the warm amber used throughout the book to a cooler slate blue. In a document where the accent color is hardcoded at every point of use — in each component's CSS, in the running header declaration, in the pull quote border — this change requires finding and replacing every occurrence. In a document built with the token system from this book, it requires changing exactly one value:

/* 01-tokens.css — one change, everywhere updates */
:root {
  /* Before: */
  --accent: hsl(25, 42%, 30%);   /* warm amber */

  /* After: */
  --accent: hsl(215, 35%, 38%);  /* slate blue */
}

Every element that uses var(--accent) — the kickers in the article headers, the left border on callout boxes, the pull quote rule weight, the footnote superscript color, the section number color in the reference list — updates automatically. The change takes thirty seconds, and a full document review confirms that the new color reads correctly in every context. This is what a properly built token system enables.

The same principle applies to more substantial design updates. If the document needs to be reformatted for a different trim size — from a 5.5 × 8.5 inch trade paperback to an A5 format — the changes required are: the size property in the default @page rule, the four margin values, and potentially the text column width in the grid template. If the type scale needs to be tightened for a more compact edition, updating the seven or eight values in 01-tokens.css adjusts the scale globally. These are not trivial changes — they require a full document review — but they are located changes, findable and understandable, not changes that require searching through the entire stylesheet looking for every affected value.

· · ·

Managing dependencies Paged.js updates and long-term stability

Every Paged.js document has a dependency: the specific version of Paged.js used to render it. Most of the time this dependency is invisible — the document renders correctly, the PDF looks right, nothing breaks. But Paged.js is actively maintained software, and new versions occasionally change rendering behavior in ways that affect existing documents. A heading that was positioned correctly in one version may be positioned differently in the next. A footnote that was placed reliably at the page foot may behave differently after an update. These are not bugs in your CSS; they are the normal consequence of a maturing specification implementation.

The practical response is to pin the Paged.js version used by a project. A package.json with a specific Paged.js version rather than a floating latest reference ensures that the document always renders against the version it was designed for:

/* package.json — pin the Paged.js version */
{
  "name": "compositor-garden",
  "version": "1.0.0",
  "description": "The Compositor's Garden — typeset with Paged.js",
  "scripts": {
    "preview": "open index.html",
    "build": "pagedjs-cli index.html --style css/07-print.css --timeout 20000 -o dist/compositor-garden.pdf",
    "build:version": "pagedjs-cli index.html --style css/07-print.css --timeout 20000 -o dist/compositor-garden-$(git describe --tags).pdf"
  },
  "devDependencies": {
    "pagedjs-cli": "0.4.3"  /* pinned — not "^0.4.3" */
  }
}

The build:version script uses git describe --tags to embed the current Git tag in the PDF filename, so each build produces a file named compositor-garden-v1.2.pdf rather than overwriting the previous output. This makes it impossible to accidentally distribute the wrong version of a document, because the filename always reflects the source version.

When you do want to update Paged.js — to access a new feature, to fix a rendering issue, or simply to stay current — treat the update as a systemic change: make no other changes alongside it, regenerate the full document, and review every page against the previous output. Diffing two PDFs page by page is tedious but reliable; tools like diff-pdf (a command-line tool) or Adobe Acrobat's Compare Documents feature can automate the detection of visual differences, flagging only the pages where rendering changed and allowing you to review those targeted pages rather than the full document.¹

· · ·

When the document changes format Reformatting as a design project

The most substantial maintenance scenario is a format change: the same content must be produced in a different trim size, for a different medium, or with a significantly different design. This is not a maintenance task — it is a new design project that reuses the content. Understanding this distinction prevents the frustration of trying to make a minor adjustment that is actually a major redesign.

The layer structure from Chapter 25 makes format changes as contained as possible. Changing the page geometry — the trim size and margins — is entirely contained in 06-page.css. The column grid may need adjustment in 04-layout.css if the new trim size significantly changes the available text column width. The typography may need rescaling in 01-tokens.css if the new format calls for a different reading distance or print size. The content files, the images, the components, and the running header strings are all untouched by a format change.

A format change that moves a document to a significantly different medium — from a printed book to a screen-first digital document, for instance — is more substantial, because the page-media layer (06-page.css) must be replaced entirely with responsive screen CSS, and the component CSS may need significant adjustment for screen reading contexts. But the typographic foundation — the tokens, the base styles, the typography rules — remains largely applicable. The work of Parts Two and Three carries over; only Parts Four and the print-specific elements of Part Five need to be rethought.

· · ·

A note on handover Making the project legible to others

The final maintenance consideration is handover: the moment when responsibility for the document passes from one person or team to another. This is inevitable in any long-lived document project, and the quality of the handover determines whether the project continues to be maintained well or begins to accumulate technical debt and visual inconsistency.

A good handover package for an HTML-CSS document project consists of four things: a clean repository with all changes committed and tagged, a README that explains how to preview and build the document, a brief design rationale document that explains the major design decisions and the reasoning behind them, and a face-to-face or written walk-through of the CSS layer structure with the person taking over. The fourth item is the most important and the most commonly omitted. Code is readable; design intent is not. A new maintainer who understands that 01-tokens.css is the only place to look for color changes, and that 06-page.css contains all the paged-media rules, and that components are self-contained in 05-components.css, will make changes confidently and correctly. A new maintainer who discovers all of this by reading the code will eventually understand it, but may make several incorrect changes in the meantime.

The design rationale does not need to be long. A short document — two or three pages — that explains why EB Garamond was chosen over a sans-serif alternative, why the margin proportions are what they are, and why the section break is a centred typographic ornament rather than a horizontal rule is enough. This document is not for the person who made the decisions — they know the reasons. It is for the person who will live with the decisions for the next five years and must either maintain them or change them with full understanding of what they are changing.