What you'll build

The 2025 annual report of Tidewell Community Energy, an invented co-operative with two wind turbines, a solar field and panels on 21 roofs. Five pages at 210 × 280 mm. On the cover, the year's wind and sun output runs as two ribbons under a 150 pt “2025”. The chair's letter, the operations report and the treasurer's accounts follow in two justified columns of Brygada 1918 on a grid of 50 lines. Full columns end on the grid's last line, and short ones end level with their neighbours. A box of three key figures crosses the chair's page with the letter cut level above it, and a note on metering floats to the head of page 4. On the closing page both columns stop on one line above the income statement. A palette attribute turns the operations pages teal and the finance page brick red.

This recipe answers

How do I get flush column bottoms and a balanced last page (vertical justification)?
How do I set a box across both columns mid-page, such as a 3-up "in numbers" panel?
How do I float a box to the top or bottom of the page while the text keeps flowing?
How do I make a table with header rows, merged cells, column widths and per-cell alignment?
How do I divide a book into parts or sections, each with its own colour and divider page?

The short answer

script.js · lines 41–56in full code

// The text block is LINES lines of LEAD deep (MARGIN.bottom is derived from them) and every
// heading takes whole lines, so a column the break rules leave short is short by whole lines.
// Balancing (on by default) stretches it back to its foot with its levers, in this order: a
// box that closes the column moves down to it; lines above the headings; one line where a
// list ends; one line under a float at the column head; last, a paragraph set one line longer
// and looser, with up to maxTracking of tracking. A closing band whose columns differ by more
// than a line is cut level instead (trailing), and so is the band a page-wide box leaves when
// it has to move on to the next page (beforeSpan).
const balancing = { maxLinesPerHeading: 1 }; // one line per heading; the next lever takes more
const flowText = { // justification, hyphenation and Knuth–Plass stay at their defaults (on)
  fontFamily: 'Brygada 1918', fontSize: pt(9.4), lineHeight: pt(LEAD),
  firstLineIndent: mm(4), indentAfterHeading: false,
  minWordSpacing: 0.7, maxWordSpacing: 1.8, // word spaces 0.7–1.8 of normal (defaults 0.6–2)
};
const onGrid = { lineHeight: pt(LEAD), marginTop: pt(LEAD), marginBottom: pt(0) }; // one line
// hook-up: headings: { balancing, levels: [..., { level: 2, ...onGrid }] }, bodyText: flowText

Flush columns: whole grid lines everywhere, and the balancing levers

Ingredients

Features: Column balancing Boxes across the page Columns inside a box Floated boxes Colours per part Widows, orphans and runts Optimal line breaking (Knuth–Plass)Figure placement Semantic colour palette Callout boxes Tables from data Named table styles Table style Cell fills Caption style Custom resource types Figures and tables as resources Covers, title pages and colophons
Also uses: Citations that place figures Heading attributes Heading styles Figures exactly here Full-width chapter band Designed openers Paragraph styles Part divider pages Running heads per section Line breaks in titles
Type: Brygada 1918, Epilogue, Spline Sans Mono, Mrs Saint Delafield (SIL OFL 1.1)
Assets: None: every picture is drawn in code
API: buildDocumentclearMeasurementCachemergeCellsregisterResourceImagerenderPageToCanvas

Method

#1 · Keep every line on the grid and let the levers close the gaps

The code is the short answer above. The text block is exactly 50 lines of 13.4 pt deep, and the bottom margin (21.6 mm) is derived from that depth. A crosshead takes one grid line above it and one for itself, so a column that ends short is short by whole lines, and whole lines are what column balancing adds. On page 3 the three-line hailstorm paragraph goes whole to page 4 under avoidOrphans, Postext's name for the rule that keeps a paragraph's last line from standing alone at the head of a column, and the right column ends two lines short. maxLinesPerHeading: 1 gives one of those lines to the space above The Saltings and the roofs and leaves the other to the next lever, which adds it after the list of roofs. At the default of 4, both lines would go above the heading.

#2 · Cut the text level above a box that crosses the page

script.js · lines 100–108in full code

// In the Markdown: :::callout{type="figures" span="page"} around :::columns{count=3 breaks="3,5"},
// each number a :::paragraphs{style="figure"} of **8.47 GWh**, then its line of text.
const figures = { id: 'figures', background: col('ink'), columnGap: mm(GUTTER),
  padding: { top: mm(5), right: mm(5), bottom: mm(5), left: mm(5) },
  marginTop: pt(LEAD), marginBottom: pt(LEAD), titleStyle: { ...boxTitle, color: col('sun') },
  body: { fontFamily: 'Epilogue', fontSize: pt(9), lineHeight: pt(12), color: col('paper'),
    ...boxText } };
const bigNumber = { id: 'figure', fontFamily: 'Epilogue', fontSize: pt(26), lineHeight: pt(31),
  color: col('paper'), boldColor: col('sun'), ...boxText };

A box with span="page" cuts a two-column page into bands. On page 2 the chair's letter stops at eight lines in each column above the box and carries on in both columns under it. Inside the box, :::columns{count=3 breaks="3,5"} opens the second and third columns at the second and third numbers (the group's third and fifth blocks) instead of cutting the run where the columns level best. The figure paragraph style sets those numbers at 26 pt, and its boldColor prints them in yellow.

#3 · Float a box to the head of the next page

script.js · lines 112–121in full code

// In the Markdown: :::callout{type="aside" span="page" placement="top"}. It leaves the flow
// where it stands and takes the head of the next page the flow opens; the text goes on
// filling this one. It has a stripe in the section's colour and no fill. The padding under
// the text drops the floats below the box by a grid line, so they stand clear of it.
const aside = { id: 'aside', backgroundEnabled: false, columnGap: mm(GUTTER),
  stripe: { enabled: true, side: 'top', width: pt(2.5), color: col('band') },
  padding: { top: mm(3.5), right: pt(0), bottom: mm(3.5), left: pt(0) },
  titleStyle: { ...boxTitle, color: col('band') },
  body: { fontFamily: 'Epilogue', fontSize: pt(8.6), lineHeight: pt(12.2), color: col('ink'),
    ...boxText } };

In the Markdown the note on metering follows the first paragraph about Harrow Down, on page 3; placement="top" takes it out of the flow and sets it at the head of the next page. The report fills the rest of page 3, and page 4 opens with the box across both columns. Under it, the site table and the ring chart, both position: 'top', head one column each, a grid line lower than they would sit without the box's 3.5 mm of bottom padding.

#4 · Give each section its colour without a divider page

script.js · lines 14–27in full code

const palette = {
  ink: '#14202b', // text: a blue-black
  band: '#0b5d7a', // sea, overridden by palette="band=#…" on the :::part fences
  wind: '#3aa6a0', sun: '#f2b134', coral: '#e2674b', // the data colours of the charts
  tint: '#eef3f5', // subtotal rows
  rule: '#c9d3d9', // hairlines
  muted: '#566370', // captions' notes and the running feet
  mist: '#9fb1bd', // small print on the ink cover
  paper: '#ffffff',
};
// Designs paint the hex (gotcha: palette-skips-designs); a :::part recolours by paletteId.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries(palette)
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));

With parts: { page: false } a fence such as :::part{number="02" title="Operations" palette="band=#1c6e67"} opens no page. It names the section for the opener strip and the running feet, and swaps band on every page until the next part. The strips, crossheads, bullets, caption labels and the aside's rule all take band, so the operations pages print in teal and the finance page in brick red, while the chair's letter keeps the base sea blue (colours per part).

#5 · Build the tables from the data, and close the last page level

script.js · lines 169–218in full code

const DATA = {
  // Output in MWh at the export meter, January to December 2025.
  wind: [560, 520, 450, 330, 270, 210, 190, 150, 300, 420, 480, 540], // Harrow Down
  sun: [90, 160, 300, 440, 560, 600, 580, 500, 380, 250, 120, 70], // the Saltings + 21 roofs
  // The turbines' year, % of the hours of both machines: [label, share, palette colour].
  hours: [['generating', 78.0, 'wind'], ['waiting for wind', 16.8, 'rule'], ['bearing repair', 2.6,
    'coral'], ['servicing and grid', 1.8, 'sun'], ['stopped for bats', 0.8, 'ink']],
  // Output by site in MWh: [site, source, capacity in MW, 2025, 2024].
  sites: [['Harrow Down', 'wind', 1.8, 4420, 4560], ['The Saltings', 'solar', 3.2, 3190, 2640],
    ['21 roofs', 'solar', 0.9, 860, 790]],
  // £ thousand, [label, 2025, 2024]; a label alone opens a group, '=' prints the running sum.
  accounts: [['Income'], ['Electricity sold under the power purchase agreement', 760, 722],
    ['Electricity sold to roof hosts', 92, 85], ['Feed-in tariff', 236, 229], ['=Total income'],
    ['Operating costs'], ['Operation and maintenance', -231, -198],
    ['Rent, rates and insurance', -158, -151], ['Staff and administration', -121, -112],
    ['Depreciation', -286, -286], ['=Operating surplus'],
    ['Interest on the Harrow Down loan', -54, -66], ['Interest on members’ shares at 3.5%', -113,
      -107], ['Grants to the Tidewell Fund', -84, -70], ['Corporation tax', -5, -7],
    ['=Surplus for the year']],
};
const fill = { background: col('tint') }; // totals sit on a tint between two hairlines
const right = (content, extra) => ({ content, align: 'right', ...extra });
const figure = (n, digits = 0) => n.toLocaleString('en-GB', { minimumFractionDigits: digits });
const head = (c, i) => (i ? right(c, { isHeader: true }) : { content: c, isHeader: true });
const siteTable = (rows) => ({ headerRowCount: 1, columnWidths: [3, 1, 1.3, 1.3], rows: [
  ['Site', 'MW', '2025', '2024'].map(head),
  ...rows.map(([site, source, mw, ...n]) => [{ content: `${site} *(${source})*` },
    right(figure(mw, 1)), ...n.map((v) => right(figure(v)))]),
  [{ content: '**All sites**', ...fill }, ...[2, 3, 4].map((i, k) => right(`**${figure(rows
    .reduce((sum, row) => sum + row[i], 0), k ? 0 : 1)}**`, fill))]] }); // the totals, summed
// Accounting style: losses in brackets, and gains followed by a no-break space as wide as a
// bracket, so the digits line up. Cells are trimmed, so a word joiner (U+2060) keeps it.
const pad = '\u00a0\u2060';
const money = (n) => (n < 0 ? `(${figure(-n)})` : `${figure(n)}${pad}`);
function statement(rows) {
  const sum = [0, 0];
  const cells = [['£ thousand', `2025${pad}`, `2024${pad}`].map(head)];
  for (const [label, ...years] of rows) {
    years.forEach((n, i) => { sum[i] += n; });
    const sub = label.startsWith('='); // a subtotal: the running sum, in bold
    cells.push(sub ? [{ content: `**${label.slice(1)}**`, ...fill },
      ...sum.map((n) => right(`**${money(n)}**`, fill))]
      : [{ content: years.length ? label : `*${label}*` }, // a label alone heads a group
        ...[0, 1].map((i) => right(years.length ? money(years[i]) : ''))]);
  }
  // mergeCells writes the cells a spanning group head hides (gotcha: merged-cells-hiddenby)
  return cells.reduce((model, row, r) => (r && !row[1].content ? mergeCells(model,
    { start: { row: r, col: 0 }, end: { row: r, col: 2 } }) : model),
  { rows: cells, headerRowCount: 1, columnWidths: [5, 1, 1] });
}

statement() turns DATA.accounts into the income statement row by row. A label that starts with = prints the running sum of each year in bold on the tint; costs are negative in the data, so Operating surplus comes out of that sum with no total typed by hand. A label with no figures, Income or Operating costs, becomes one italic cell across the table, merged with mergeCells, which also writes the placeholder cells a merge needs. On page 5 the statement floats across the foot of the page, under the treasurer's report, which closes the document. Unbalanced, the columns would run to 12 lines on the left and 9 on the right; the trailing cut sets both at 11, and the heading lever adds the line the right column still lacks above Cash and reserves.

The whole recipe

// ═══ Postext Cookbook · Nº 037 · Annual report with flush columns ═══════════════════════
// https://postext.dev/en/cookbook/annual-report-flush-columns
// Code: MIT · Text: original (CC BY 4.0) · Art: drawn in code · Typefaces: SIL OFL 1.1
// Fonts: Brygada 1918, Epilogue, Spline Sans Mono, Mrs Saint Delafield · Needs postext ≥ 1.4.1
import {
  buildDocument, renderPageToCanvas, clearMeasurementCache, registerResourceImage, mergeCells,
} from 'https://esm.sh/postext';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'annual-report-flush-columns';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: 'band' is the first section's colour; each later :::part brings its own
const palette = {
  ink: '#14202b', // text: a blue-black
  band: '#0b5d7a', // sea, overridden by palette="band=#…" on the :::part fences
  wind: '#3aa6a0', sun: '#f2b134', coral: '#e2674b', // the data colours of the charts
  tint: '#eef3f5', // subtotal rows
  rule: '#c9d3d9', // hairlines
  muted: '#566370', // captions' notes and the running feet
  mist: '#9fb1bd', // small print on the ink cover
  paper: '#ffffff',
};
// Designs paint the hex (gotcha: palette-skips-designs); a :::part recolours by paletteId.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries(palette)
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TRIM = { width: 210, height: 280 };
const LEAD = 13.4; // body leading in pt: one line of the baseline grid
const LINES = 50; // grid lines in a full column
const MARGIN = { top: 22, inner: 18, outer: 16 }; // mm, mirrored
MARGIN.bottom = TRIM.height - MARGIN.top - (LINES * LEAD * 25.4) / 72; // 21.6 mm: 50 lines exactly
const GUTTER = 7; // mm between the columns, and between the columns inside the boxes
const mono = { fontFamily: 'Spline Sans Mono', fontWeight: 500, textTransform: 'uppercase' };
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const text = (id, content, look, placement) => ({ kind: 'text', id, content, placement,
  align: 'left', ...look });

// #region answer: flush columns: whole grid lines everywhere, and the balancing levers
// The text block is LINES lines of LEAD deep (MARGIN.bottom is derived from them) and every
// heading takes whole lines, so a column the break rules leave short is short by whole lines.
// Balancing (on by default) stretches it back to its foot with its levers, in this order: a
// box that closes the column moves down to it; lines above the headings; one line where a
// list ends; one line under a float at the column head; last, a paragraph set one line longer
// and looser, with up to maxTracking of tracking. A closing band whose columns differ by more
// than a line is cut level instead (trailing), and so is the band a page-wide box leaves when
// it has to move on to the next page (beforeSpan).
const balancing = { maxLinesPerHeading: 1 }; // one line per heading; the next lever takes more
const flowText = { // justification, hyphenation and Knuth–Plass stay at their defaults (on)
  fontFamily: 'Brygada 1918', fontSize: pt(9.4), lineHeight: pt(LEAD),
  firstLineIndent: mm(4), indentAfterHeading: false,
  minWordSpacing: 0.7, maxWordSpacing: 1.8, // word spaces 0.7–1.8 of normal (defaults 0.6–2)
};
const onGrid = { lineHeight: pt(LEAD), marginTop: pt(LEAD), marginBottom: pt(0) }; // one line
// hook-up: headings: { balancing, levels: [..., { level: 2, ...onGrid }] }, bodyText: flowText
// #endregion

// #region openers: the cover and the section openers, fed by heading attributes
const cover = { enabled: true, slot: { elements: [
  { kind: 'box', id: 'field', style: { backgroundColor: col('ink') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: 'fill' } } },
  { kind: 'image', id: 'ribbons', resourceId: 'ribbons', // 210 × 128 mm, from DATA
    placement: { ...at('bleed', 'top-left', 0, 104), size: { width: 'fill' } } },
  text('name', '{titleText}', { fontFamily: 'Epilogue', fontWeight: 800, fontSize: pt(19),
    color: col('paper') }, at('page', 'top-left', MARGIN.inner, MARGIN.top)),
  text('year', '{attr.year}', { fontFamily: 'Epilogue', fontWeight: 800, fontSize: pt(150),
    lineHeight: 0.9, letterSpacing: pt(-2), color: col('paper') }, at('#name', 'below', -2, 4)),
  text('strap', '{attr.strap}', { fontFamily: 'Epilogue', fontSize: pt(19), color: col('sun') },
    at('#year', 'below', 2, 2)),
  text('period', '{attr.period}', { ...mono, fontSize: pt(7.5), letterSpacing: pt(1.3),
    color: col('paper') }, at('#strap', 'below', 0, 3)),
  text('note', '{attr.note}', { fontFamily: 'Epilogue', fontSize: pt(6.5), color: col('mist'),
    overflow: 'wrap' }, { ...at('page', 'bottom-left', MARGIN.inner, -14), // the text block's
    size: { width: mm(TRIM.width - MARGIN.inner - MARGIN.outer) } }), // width: 'fill' hits the trim
] } };
// A section opener: a strip in the part's colour, then title and standfirst. Design text's
// lineHeight is a multiple of its size (gotcha: design-lineheight-multiple).
const STRIP = 8; // mm
const onStrip = { ...mono, fontSize: pt(8), letterSpacing: pt(1.4), color: col('paper') };
const opener = { enabled: true, minHeight: mm(56), slot: { elements: [
  { kind: 'box', id: 'strip', style: { backgroundColor: col('band') },
    placement: { ...at('container', 'top-left'), size: { width: 'fill', height: mm(STRIP) } } },
  text('part', '{partNumber}   {partTitle}', onStrip, // a text given a height centres on it
    { ...at('container', 'top-left', 3), size: { height: mm(STRIP) } }),
  text('kicker', '{attr.kicker}', { ...onStrip, align: 'right' },
    { ...at('container', 'top-right', -3), size: { height: mm(STRIP) } }),
  text('title', '{titleText}', { fontFamily: 'Epilogue', fontWeight: 800, fontSize: pt(26),
    lineHeight: 1.04, color: col('ink'), overflow: 'wrap' }, // breaks at the title's \\
  { ...at('#strip', 'below', 0, 8), size: { width: 'fill' } }),
  text('standfirst', '{attr.standfirst}', { fontFamily: 'Brygada 1918', italic: true,
    fontSize: pt(11.5), lineHeight: 1.3, color: col('ink'), overflow: 'wrap' },
  { ...at('#title', 'below', 0, 3.5), size: { width: mm(150) } }),
] } };
// #endregion

const boxText = { textAlign: 'left', firstLineIndent: pt(0) };
const boxTitle = { ...mono, fontSize: pt(7.5), letterSpacing: pt(1.3), gap: mm(3) };
// #region figures: a page-wide box of three key figures, one to a column
// In the Markdown: :::callout{type="figures" span="page"} around :::columns{count=3 breaks="3,5"},
// each number a :::paragraphs{style="figure"} of **8.47 GWh**, then its line of text.
const figures = { id: 'figures', background: col('ink'), columnGap: mm(GUTTER),
  padding: { top: mm(5), right: mm(5), bottom: mm(5), left: mm(5) },
  marginTop: pt(LEAD), marginBottom: pt(LEAD), titleStyle: { ...boxTitle, color: col('sun') },
  body: { fontFamily: 'Epilogue', fontSize: pt(9), lineHeight: pt(12), color: col('paper'),
    ...boxText } };
const bigNumber = { id: 'figure', fontFamily: 'Epilogue', fontSize: pt(26), lineHeight: pt(31),
  color: col('paper'), boldColor: col('sun'), ...boxText };
// #endregion

// #region aside: a box that floats to the head of the next page while the text flows on
// In the Markdown: :::callout{type="aside" span="page" placement="top"}. It leaves the flow
// where it stands and takes the head of the next page the flow opens; the text goes on
// filling this one. It has a stripe in the section's colour and no fill. The padding under
// the text drops the floats below the box by a grid line, so they stand clear of it.
const aside = { id: 'aside', backgroundEnabled: false, columnGap: mm(GUTTER),
  stripe: { enabled: true, side: 'top', width: pt(2.5), color: col('band') },
  padding: { top: mm(3.5), right: pt(0), bottom: mm(3.5), left: pt(0) },
  titleStyle: { ...boxTitle, color: col('band') },
  body: { fontFamily: 'Epilogue', fontSize: pt(8.6), lineHeight: pt(12.2), color: col('ink'),
    ...boxText } };
// #endregion

// Running feet: the folio outside, the report on the verso, the section in its colour opposite.
const foot = (id, content, parity, x, look = {}) => text(id, content, { ...mono, fontSize: pt(7),
  letterSpacing: pt(1.1), color: col('muted'), parity, align: x < 0 ? 'right' : 'left', ...look },
at('page', x < 0 ? 'bottom-right' : 'bottom-left', x, -11));
const folio = { fontWeight: 700, color: col('ink') };
const footer = { elements: [
  foot('verso-folio', '{pageNumber}', 'even', MARGIN.outer, folio),
  foot('verso-title', '{title}  ·  {subtitle}', 'even', MARGIN.outer + 8),
  foot('recto-folio', '{pageNumber}', 'odd', -MARGIN.outer, folio),
  foot('recto-part', '{partTitle}', 'odd', -(MARGIN.outer + 8), { color: col('band') }),
] };

const config = () => ({ // a factory: the engine caches resolved configs per object
  colorPalette, resourceTypes,
  page: { width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150,
    margins: { top: mm(MARGIN.top), bottom: mm(MARGIN.bottom), left: mm(MARGIN.inner),
      right: mm(MARGIN.outer), mirror: true } },
  layout: { gutterWidth: mm(GUTTER) }, // two columns, the default
  // Bold, italic and references default to the engine's blue, so all three are restated in ink.
  bodyText: { ...flowText, color: col('ink'), boldColor: col('ink'), italicColor: col('ink'),
    referenceColor: col('ink'), referenceBold: false },
  headings: { fontFamily: 'Epilogue', color: col('band'), balancing, levels: [
    // Restated (gotcha: headings-drop-h1-break); 'any': a section opens on the next page.
    { level: 1, span: 'page', breakBefore: { enabled: true, parity: 'any' },
      advancedDesign: opener },
    { level: 2, fontSize: pt(11.5), fontWeight: 700, ...onGrid },
  ] },
  headingStyles: [{ id: 'cover', advancedDesign: cover, footer: { elements: [] } }], // no folio
  parts: { page: false }, // a :::part sets the section's title and colour, with no page
  unorderedLists: { bulletChar: '–', color: col('band'), marginTop: pt(0), marginBottom: pt(0) },
  calloutStyles: [figures, aside],
  paragraphStyles: [bigNumber, { id: 'signoff', fontFamily: 'Epilogue', fontSize: pt(8.5),
    ...boxText }],
  tableStyle: { rules: 'horizontal', borderColor: col('rule'), borderWidth: pt(0.5),
    headerBackground: col('ink'), headerColor: col('paper'), headerFontFamily: 'Spline Sans Mono',
    headerFontSize: pt(7.5), bodyFontFamily: 'Spline Sans Mono', bodyFontSize: pt(7.8),
    bodyColor: col('ink'), cellPadding: mm(1.3) },
  tableStyles: [{ id: 'statement', cellPadding: mm(0.9) }], // 17 rows, set closer
  captionStyle: { fontFamily: 'Epilogue', fontSize: pt(8), color: col('ink'), gap: mm(2.5),
    labelColor: col('band'), note: { fontSize: pt(7), color: col('muted') } },
  header: { elements: [] }, footer,
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
// #region data: one object for the cover, both charts and the income statement
const DATA = {
  // Output in MWh at the export meter, January to December 2025.
  wind: [560, 520, 450, 330, 270, 210, 190, 150, 300, 420, 480, 540], // Harrow Down
  sun: [90, 160, 300, 440, 560, 600, 580, 500, 380, 250, 120, 70], // the Saltings + 21 roofs
  // The turbines' year, % of the hours of both machines: [label, share, palette colour].
  hours: [['generating', 78.0, 'wind'], ['waiting for wind', 16.8, 'rule'], ['bearing repair', 2.6,
    'coral'], ['servicing and grid', 1.8, 'sun'], ['stopped for bats', 0.8, 'ink']],
  // Output by site in MWh: [site, source, capacity in MW, 2025, 2024].
  sites: [['Harrow Down', 'wind', 1.8, 4420, 4560], ['The Saltings', 'solar', 3.2, 3190, 2640],
    ['21 roofs', 'solar', 0.9, 860, 790]],
  // £ thousand, [label, 2025, 2024]; a label alone opens a group, '=' prints the running sum.
  accounts: [['Income'], ['Electricity sold under the power purchase agreement', 760, 722],
    ['Electricity sold to roof hosts', 92, 85], ['Feed-in tariff', 236, 229], ['=Total income'],
    ['Operating costs'], ['Operation and maintenance', -231, -198],
    ['Rent, rates and insurance', -158, -151], ['Staff and administration', -121, -112],
    ['Depreciation', -286, -286], ['=Operating surplus'],
    ['Interest on the Harrow Down loan', -54, -66], ['Interest on members’ shares at 3.5%', -113,
      -107], ['Grants to the Tidewell Fund', -84, -70], ['Corporation tax', -5, -7],
    ['=Surplus for the year']],
};
const fill = { background: col('tint') }; // totals sit on a tint between two hairlines
const right = (content, extra) => ({ content, align: 'right', ...extra });
const figure = (n, digits = 0) => n.toLocaleString('en-GB', { minimumFractionDigits: digits });
const head = (c, i) => (i ? right(c, { isHeader: true }) : { content: c, isHeader: true });
const siteTable = (rows) => ({ headerRowCount: 1, columnWidths: [3, 1, 1.3, 1.3], rows: [
  ['Site', 'MW', '2025', '2024'].map(head),
  ...rows.map(([site, source, mw, ...n]) => [{ content: `${site} *(${source})*` },
    right(figure(mw, 1)), ...n.map((v) => right(figure(v)))]),
  [{ content: '**All sites**', ...fill }, ...[2, 3, 4].map((i, k) => right(`**${figure(rows
    .reduce((sum, row) => sum + row[i], 0), k ? 0 : 1)}**`, fill))]] }); // the totals, summed
// Accounting style: losses in brackets, and gains followed by a no-break space as wide as a
// bracket, so the digits line up. Cells are trimmed, so a word joiner (U+2060) keeps it.
const pad = '\u00a0\u2060';
const money = (n) => (n < 0 ? `(${figure(-n)})` : `${figure(n)}${pad}`);
function statement(rows) {
  const sum = [0, 0];
  const cells = [['£ thousand', `2025${pad}`, `2024${pad}`].map(head)];
  for (const [label, ...years] of rows) {
    years.forEach((n, i) => { sum[i] += n; });
    const sub = label.startsWith('='); // a subtotal: the running sum, in bold
    cells.push(sub ? [{ content: `**${label.slice(1)}**`, ...fill },
      ...sum.map((n) => right(`**${money(n)}**`, fill))]
      : [{ content: years.length ? label : `*${label}*` }, // a label alone heads a group
        ...[0, 1].map((i) => right(years.length ? money(years[i]) : ''))]);
  }
  // mergeCells writes the cells a spanning group head hides (gotcha: merged-cells-hiddenby)
  return cells.reduce((model, row, r) => (r && !row[1].content ? mergeCells(model,
    { start: { row: r, col: 0 }, end: { row: r, col: 2 } }) : model),
  { rows: cells, headerRowCount: 1, columnWidths: [5, 1, 1] });
}
// #endregion

// Charts and tables numbered through the report, tables captioned above; marks go unnumbered.
const type = (id, name, extra) => ({ id, name, captionPrefix: name,
  numberingTemplate: '{n}', resetOn: 'never', counterFormat: 'decimal', ...extra });
const resourceTypes = [type('chart', 'Chart'), type('table', 'Table', { captionStyle:
  { position: 'above' } }), type('mark', 'Mark', { captionPrefix: '', numberingTemplate: '' })];
const svg = (id, typeId, fileId, [width, height], extra) => ({ id, typeId, kind: 'svg',
  createdAt: 0, updatedAt: 0, svg: { fileId, width, height }, ...extra });
const table = (id, model, { styleId, ...extra }) => ({ id, typeId: 'table', kind: 'table',
  createdAt: 0, updatedAt: 0, table: { model, styleId }, ...extra });
const resources = [
  svg('ribbons', 'mark', 'ribbons.svg', [2100, 1280], { altText: 'A teal and a yellow ribbon '
    + 'swell and cross from January to December with the wind and sun output.' }),
  svg('monthly', 'chart', 'monthly.svg', [1760, 560], { placement: { position: 'bottom',
    span: 'page' }, note: 'Measured at the export meters. Turbine 2 stood still 4–23 August.',
  caption: 'Output by month in 2025, in megawatt-hours: :swatch{color="wind"} wind at Harrow '
    + 'Down and :swatch{color="sun"} sun on the Saltings and the 21 roofs.',
  altText: 'Paired bars by month: wind falls from 560 MWh in January to 150 in August, sun peaks '
    + 'at 600 in June.' }),
  svg('hours', 'chart', 'hours.svg', [845, 470], { placement: { position: 'top' },
    caption: 'How the two turbines spent the 17,520 hours of their year.',
    altText: DATA.hours.map(([label, share]) => `${label} ${share.toFixed(1)}%`).join(', ') }),
  svg('signature', 'mark', 'signature.svg', [420, 150], { placement: { position: 'here',
    width: 0.42 }, altText: 'The chair’s signature.' }),
  table('sites', siteTable(DATA.sites), { placement: { position: 'top' }, // the house style
    caption: 'Output by site, in megawatt-hours.' }),
  table('accounts', statement(DATA.accounts), { placement: { position: 'bottom', span: 'page' },
    caption: 'Income statement for the year to 31 December.', styleId: 'statement',
    note: 'Audited. Figures in brackets are costs; the full accounts are available on request.' }),
];

const markdown = String.raw`---
Markdown sample · 125 lines · content.en.md
title: "Tidewell Community Energy"
subtitle: "Annual report and accounts 2025"
author: "Tidewell Community Energy"
---

# Tidewell Community Energy {style="cover" year="2025" strap="Annual report and accounts" period="For the year to 31 December 2025" note="The cover draws our output month by month, January to December: wind in teal, sun in yellow. Tidewell is a fictional co-operative, and every name and figure in this report is invented. Set in Brygada 1918, Epilogue, Spline Sans Mono and Mrs Saint Delafield (SIL OFL)."}

:::part{number="01" title="The year"}
:::

# The wind and the sun \\ took turns {kicker="From the chair" standfirst="Output rose 6% to 8.47 gigawatt-hours, 188 people joined the co-op and the Tidewell Fund gave £84,000 to 23 projects in the town."}

Dear members,

Last January the turbines on Harrow Down had their windiest month since we put them up in 2015, and in June the panels on the Saltings and on 21 roofs around the town made more electricity than in any month we have metered. Together they made 8.47 gigawatt-hours in the year, 6% more than in 2024. At the regulator’s figure of 2,700 kilowatt-hours for a typical home, that is the yearly use of about 3,100 households, more than there are in Tidewell itself.

The board was most pleased by how evenly the output was spread over the year. The turbines are strongest from October to March and the panels from April to September, and in 2025 each covered for the other so well that no month fell below 600 megawatt-hours. The operations report shows the two side by side.

:::callout{type="figures" span="page" title="2025 in three numbers"}
:::columns{count=3 breaks="3,5"}
:::paragraphs{style="figure"}
**8.47 GWh**
:::

generated by our turbines and panels, 6% more than in 2024

:::paragraphs{style="figure"}
**2,316**
:::

members at 31 December, 188 of them new this year

:::paragraphs{style="figure"}
**£84,000**
:::

granted by the Tidewell Fund to 23 projects in the town
:::
:::

The costliest setback came in August, when the main bearing of turbine 2 began to fail and the machine stood still for 19 days while a crane crew replaced it. Our insurer paid most of the bill, but the part it did not cover, together with the lost output, is the main reason why the surplus is a little smaller than last year’s. The treasurer explains the effect on the accounts in her report.

Membership grew to 2,316 by the end of December. In all, 188 people joined, most of them through the share offer we ran with the three primary schools in May, and 31 withdrew their shares, nearly all of them because they had moved away. Our youngest member is nine; her shares were a birthday present. We paid 3.5% interest on shares for the eighth year running. The Tidewell Fund, which takes a share of each year’s surplus, made 23 grants worth £84,000. They paid for loft insulation in the scout hut and the chapel hall, a library of electric cargo bikes and a warm-homes advice service that visited 140 households last winter.

In the coming year we will ask you to approve our largest investment since the Saltings: a battery beside the solar field that stores 2 megawatt-hours, so that we can sell the midday output in the evening, when the grid pays most for it. The district council gave planning permission in November. The board will present the business case at the annual general meeting on 14 May, and members will decide there by a simple majority.

Volunteers read the 21 roof meters every month, and eleven of them share the shifts on our stall at the Saturday market. Thank you to them, to the staff in the office on Quay Street, and to every member for trusting the co-op with their savings. I look forward to seeing many of you in May.

::resource{id="signature"}

:::paragraphs{style="signoff"}
Maren Coles, chair of the board
:::

:::part{number="02" title="Operations" palette="band=#1c6e67"}
:::

# Harrow Down, the Saltings \\ and 21 roofs {kicker="Operations report" standfirst="How two wind turbines, a solar field and the panels on schools, halls and the fire station ran in 2025. By Dev Okafor, operations manager."}

Our three sites generated 8,470 megawatt-hours of electricity in 2025, up from 7,990 the year before (:ref{id="monthly"}). The turbines made 4,420 of them and the panels 4,050: it is the first year in which the sun came within a tenth of the wind. Every figure in this report is measured at the export meter, and the box overleaf explains what that means.

## Harrow Down

The two 900-kilowatt turbines ran at an average capacity factor of 28.0%, against 28.8% in 2024. January was their windiest month since they were commissioned in 2015, at 560 megawatt-hours, with a gust of 31 metres a second recorded at hub height on the 24th. The storm cost us nothing but a tripped breaker at the substation, reset within the hour.

:::callout{type="aside" span="page" placement="top" title="How we count a kilowatt-hour"}
:::columns{count=2 breaks="2"}
Every site has two meters. The turbines and inverters log what they generate, and a meter owned by the grid operator records what leaves the site. The figures in this report are the second kind: what the grid bought from us, after the site’s own use and the losses in cables and transformers, which come to about 2% at Harrow Down.

The grid operator reads the export meters every half hour, and each month we check its readings against our own logs. Where the two disagree by more than 1%, the operator’s reading stands, because it is the one we are paid for. Roof hosts are billed from their own meters, read by a volunteer on the first Saturday of each month.
:::
:::

Turbine 2 lost 19 days in August. A vibration alarm on 4 August led to an inspection that found spalling on the races of the main bearing, and we stopped the machine rather than risk the gearbox behind it. The replacement came from the manufacturer’s store in Bremen, a crane crew fitted it in two days of calm weather, and the turbine was back in service on 23 August. Turbine 1 ran through the summer, stopping only for its scheduled service in June.

## The Saltings and the roofs

The solar field produced 3,190 megawatt-hours from its 3.2 megawatts of panels, or 997 kilowatt-hours for every kilowatt installed, its best since it opened in 2019. June was the strongest month on record for our panels, at 600 megawatt-hours across all sites.

On the 21 roofs the panels made 860 megawatt-hours (:ref{id="sites"}). The three largest roofs were:

- Tidewell Academy, 212 megawatt-hours;
- the leisure centre, 148;
- the fire station, 61.

Roof hosts used 610 megawatt-hours on site, at 15p a kilowatt-hour, well below what a supplier would charge, and the rest went to the grid.

In March a hailstorm cracked 38 panels at Saltmarsh Primary. The installer replaced them under warranty within a fortnight.

## Availability

The turbines were available for 94.8% of the hours in the year, down from 97.9% in 2024 (:ref{id="hours"}). The hours they could not run, counted across both machines, were lost to:

- the bearing repair on turbine 2, 2.6% of the year;
- servicing and grid outages, 1.8%;
- the summer nights stopped for bats, 0.8%: both turbines stop on warm, calm nights from May to September, when bats feed around the towers, as the planning consent requires.

For the rest of the year the turbines were either generating, 78.0% of the hours, or waiting with the wind below the 3 metres a second they need to start turning. The maintenance contract with the manufacturer guarantees 97% availability, and it pays us for the output lost below that level: £21,000 for 2025, which appears in the accounts as a reduction in maintenance costs.

## Grid limits

On eleven sunny afternoons in May and June the distribution network operator asked us to cap the Saltings’ export at half its capacity while it rebuilt the overhead line at Marsh End. It paid us for the 64 megawatt-hours we could not export, at the price in our power purchase agreement; they are left out of this report’s output figures. The rebuilt line can carry the field’s full output, so the caps should not return.

## The sites

Nobody was hurt at work on our sites in 2025, our tenth year without a lost-time accident. A flock of 140 Southdown ewes kept the grass short under the panels on the Saltings from March to October; they belong to a farmer in the next parish, who pays no rent for the grazing. In June the ecologist’s survey counted 31 skylark territories in the field margins, against 24 before the field was built. Three schools and a Scout group came to the open day at Harrow Down in September.

## The year ahead

Turbine 1 is due the ten-year inspection of its gearbox in April, and we have booked the work for a week with a low wind forecast. On the Saltings we will replace the fence along the sea wall, which the winter tides have undermined in two places, and plant the hawthorn hedge that the planning consent asked for. If members approve the battery in May, the connection works would start in the autumn, and the battery could be storing the field’s midday output by the summer of 2027.

:::part{number="03" title="Finances" palette="band=#b0452c"}
:::

# Paying 3.5% and still \\ adding to reserves {kicker="Treasurer’s report" standfirst="Income rose 5% to £1.09 million. After interest, grants and tax, the co-op kept a surplus of £36,000. By Alison Pryce, treasurer."}

Our income for the year was £1,088,000, 5% more than in 2024 (:ref{id="accounts"}). Almost all of the increase came from selling more electricity: the price set in our power purchase agreement hardly changed at its review in April.

Costs rose by £49,000. Operation and maintenance came to £231,000, £33,000 more than in 2024: the bearing repair cost us £54,000 after insurance, and the manufacturer’s availability guarantee paid back £21,000.

Out of an operating surplus of £292,000, the co-op paid £54,000 of interest on the loan that built Harrow Down, which ends in 2031, and £113,000 of interest on members’ shares. The board then gave £84,000 to the Tidewell Fund and £5,000 went in corporation tax, leaving £36,000 to add to reserves.

## Cash and reserves

At the end of the year the co-op held £612,000 in cash, of which £400,000 is set aside for the gearbox overhauls due in 2027 and 2028. Members’ share capital stood at £3.24 million: the 188 new members bought £94,000 of shares and the 31 who left withdrew £64,000.
`; // content.<lang>.md, inlined by the Cookbook

// #region art: the cover's ribbons and the charts, drawn from DATA with the page's palette
const MONTHS = ['J', 'F', 'M', 'A', 'M', 'J', 'J', 'A', 'S', 'O', 'N', 'D'];
const n2 = (v) => +v.toFixed(2);
// An SVG drawn as an image cannot see the page's web fonts (gotcha: svg-no-webfonts), so each
// drawing carries its face inline, as a data URL of the Fontsource file.
async function inlineFace(family, weight) {
  const id = family.toLowerCase().replace(/\s+/g, '-');
  const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-latin-${weight}`
    + '-normal.woff2';
  const bytes = new Uint8Array(await (await fetch(url)).arrayBuffer());
  let bin = '';
  for (const b of bytes) bin += String.fromCharCode(b);
  return `<style>@font-face{font-family:F;src:url(data:font/woff2;base64,${btoa(bin)}) `
    + `format('woff2')}text{font-family:F}</style>`;
}
// A smooth path through points (Catmull–Rom turned into cubic Béziers).
function smooth(pts) {
  let d = `M${n2(pts[0][0])} ${n2(pts[0][1])}`;
  for (let i = 0; i < pts.length - 1; i++) {
    const [p0, p1, p2, p3] = [pts[i - 1] ?? pts[i], pts[i], pts[i + 1], pts[i + 2] ?? pts[i + 1]];
    const c1 = [p1[0] + (p2[0] - p0[0]) / 6, p1[1] + (p2[1] - p0[1]) / 6];
    const c2 = [p2[0] - (p3[0] - p1[0]) / 6, p2[1] - (p3[1] - p1[1]) / 6];
    d += `C${n2(c1[0])} ${n2(c1[1])} ${n2(c2[0])} ${n2(c2[1])} ${n2(p2[0])} ${n2(p2[1])}`;
  }
  return d;
}
// The cover: each source is a ribbon as thick as its month's output; the stronger one rides
// higher, so they cross twice: in spring and in autumn. 210 × 128 mm, the months 17.5 mm apart.
function ribbonsArt(face) {
  const [W, H, MID, THICK, SPREAD] = [210, 128, 64, 0.065, 0.09]; // mm, mm per MWh
  const x = (i) => 8.75 + i * 17.5;
  const edge = (i) => [-8.75, ...DATA.wind.map((_, m) => x(m)), W + 8.75][i];
  const layer = (own, other, colour) => {
    const pts = [own[0], ...own, own[11]].map((v, i) => {
      const m = Math.min(11, Math.max(0, i - 1));
      return [edge(i), MID - (v - other[m]) * SPREAD, (v * THICK) / 2];
    });
    let strands = '';
    for (const k of [-0.66, -0.33, 0, 0.33, 0.66]) {
      strands += `<path d="${smooth(pts.map(([px, py, h]) => [px, py + k * h]))}" fill="none" `
        + `stroke="${palette.ink}" stroke-opacity="0.18" stroke-width="0.3"/>`;
    }
    const top = pts.map(([px, py, h]) => [px, py - h]);
    const bottom = pts.map(([px, py, h]) => [px, py + h]).reverse();
    return `<path d="${smooth(top)}L${smooth(bottom).slice(1)}Z" fill="${colour}" `
      + `fill-opacity="0.9"/>${strands}`;
  };
  const ticks = MONTHS.map((m, i) => `<circle cx="${x(i)}" cy="${H - 12}" r="0.7" `
    + `fill="${palette.mist}"/><text x="${x(i)}" y="${H - 5}" font-size="3" text-anchor="middle" `
    + `fill="${palette.mist}">${m}</text>`).join('');
  // Each ribbon is labelled inside the text block: the wind in February, the sun in June.
  const label = (name, m, own, other, ink) => `<text x="${x(m)}" y="${n2(MID - (own[m] - other[m])
    * SPREAD + 1.2)}" font-size="3.4" letter-spacing="0.6" text-anchor="middle" fill="${ink}">`
    + `${name}</text>`;
  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W * 10}" height="${H * 10}" `
    + `viewBox="0 0 ${W} ${H}">${face}${layer(DATA.sun, DATA.wind, palette.sun)}`
    + `${layer(DATA.wind, DATA.sun, palette.wind)}${ticks}`
    + `${label('WIND', 1, DATA.wind, DATA.sun, palette.ink)}`
    + `${label('SUN', 5, DATA.sun, DATA.wind, palette.ink)}</svg>`;
}
// Chart 1: paired bars on a 200 MWh grid, 176 × 56 mm (the width of the text block).
function monthlyArt(face) {
  const [W, H, LEFT, BASE, TOPV] = [176, 56, 12, 48, 700];
  const y = (v) => BASE - (v / TOPV) * (BASE - 2);
  const step = (W - LEFT) / 12;
  let grid = '';
  for (const v of [0, 200, 400, 600]) {
    grid += `<path d="M${LEFT} ${n2(y(v))}H${W}" stroke="${v ? palette.rule : palette.ink}" `
      + `stroke-width="${v ? 0.2 : 0.35}"/><text x="${LEFT - 2}" y="${n2(y(v) + 1)}" `
      + `font-size="2.6" text-anchor="end" fill="${palette.muted}">${v}</text>`;
  }
  const bars = MONTHS.map((m, i) => {
    const cx = LEFT + step * (i + 0.5);
    const bar = (v, dx, fill) => `<rect x="${n2(cx + dx)}" y="${n2(y(v))}" width="4.4" `
      + `height="${n2(BASE - y(v))}" fill="${fill}"/>`;
    return bar(DATA.wind[i], -4.6, palette.wind) + bar(DATA.sun[i], 0.2, palette.sun)
      + `<text x="${n2(cx)}" y="${BASE + 5}" font-size="2.8" text-anchor="middle" `
      + `fill="${palette.ink}">${m}</text>`;
  }).join('');
  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W * 10}" height="${H * 10}" `
    + `viewBox="0 0 ${W} ${H}">${face}${grid}${bars}</svg>`;
}
// Chart 2: a ring of the turbines' hours with its key beside it, 84.5 × 47 mm (one column).
function hoursArt(face) {
  const [W, H, CX, CY, R, T] = [84.5, 47, 22, 23.5, 20, 7];
  let a0 = -Math.PI / 2;
  let ring = '';
  let key = '';
  DATA.hours.forEach(([label, share, colour], i) => {
    const a1 = a0 + (share / 100) * 2 * Math.PI;
    const p = (a, r) => `${n2(CX + r * Math.cos(a))} ${n2(CY + r * Math.sin(a))}`;
    const big = a1 - a0 > Math.PI ? 1 : 0;
    ring += `<path d="M${p(a0, R)}A${R} ${R} 0 ${big} 1 ${p(a1, R)}L${p(a1, R - T)}`
      + `A${R - T} ${R - T} 0 ${big} 0 ${p(a0, R - T)}Z" fill="${palette[colour]}" `
      + `stroke="${palette.paper}" stroke-width="0.3"/>`;
    const ky = 8 + i * 7.5;
    key += `<rect x="50" y="${ky - 2.6}" width="3" height="3" fill="${palette[colour]}"/>`
      + `<text x="55" y="${ky}" font-size="2.9" fill="${palette.ink}">${share.toFixed(1)}%</text>`
      + `<text x="55" y="${ky + 3.4}" font-size="2.5" fill="${palette.muted}">${label}</text>`;
    a0 = a1;
  });
  const available = DATA.hours.slice(0, 2).reduce((sum, [, share]) => sum + share, 0); // 94.8
  const middle = `<text x="${CX}" y="${CY + 1.2}" font-size="4" text-anchor="middle" `
    + `fill="${palette.ink}">${available.toFixed(1)}%</text><text x="${CX}" y="${CY + 5}" `
    + `font-size="2.2" text-anchor="middle" fill="${palette.muted}">available</text>`;
  return `<svg xmlns="http://www.w3.org/2000/svg" width="${W * 10}" height="${H * 10}" `
    + `viewBox="0 0 ${W} ${H}">${face}${ring}${middle}${key}</svg>`;
}
// The chair's signature: her name in a script face, and the stroke she draws under it.
function signatureArt(face) {
  return '<svg xmlns="http://www.w3.org/2000/svg" width="420" height="150" viewBox="0 0 42 15">'
    + `${face}<text x="1" y="10" font-size="10" fill="${palette.band}">Maren Coles</text>`
    + '<path d="M3 13.2C14 12.1 27 12.6 40 11.3" fill="none" '
    + `stroke="${palette.band}" stroke-width="0.35" stroke-linecap="round"/></svg>`;
}
async function drawArt() {
  const [face, hand] = await Promise.all([inlineFace('Spline Sans Mono', 500),
    inlineFace('Mrs Saint Delafield', 400)]);
  await Promise.all([loadSvg('ribbons.svg', ribbonsArt(face)), loadSvg('monthly.svg',
    monthlyArt(face)), loadSvg('hours.svg', hoursArt(face)), loadSvg('signature.svg',
    signatureArt(hand))]);
}
// #endregion

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
const FONTS = { // text, display and label faces, loaded before the build (gotcha: fonts-first)
  'Brygada 1918': ['400', '400i', '700'], // 700: the list dashes
  Epilogue: ['400', '700', '800'], // 700: the crossheads; 800: the display
  'Spline Sans Mono': ['400', '400i', '500', '700'], 'Mrs Saint Delafield': ['400'] }; // signature

// ─── 4 · Build & show ───────────────────────────────────────────────────────
await loadFonts(FONTS, markdown);
await drawArt();
const doc = await buildWithFonts(() => buildDocument({ markdown, resources }, config()), markdown);
showPages(doc, { title: t({ en: 'Annual report with flush columns',
  es: 'Memoria anual con columnas a ras' }) });

Kit · core, fonts, viewer, images: the same in every recipe · 270 lines
// ─── Kit ── helpers shared by every Cookbook recipe · postext.dev/cookbook ─────

// ─── Kit · core v1 ── the same in every recipe · postext.dev/cookbook ─────────
function mm(value) { return { value, unit: 'mm' }; }
function pt(value) { return { value, unit: 'pt' }; }
function em(value) { return { value, unit: 'em' }; }
/** The sample language's string: t({ en: 'Figure', es: 'Figura' }). */
function t(strings) { return strings[LANG] ?? Object.values(strings)[0]; }
/** A file in this recipe's assets folder, served from the Postext repo by jsDelivr. */
function asset(file) { return `https://cdn.jsdelivr.net/gh/drnachio/postext@main/cookbook/${RECIPE}/assets/${file}`; }

// ─── Kit · fonts v1 ── the same in every recipe · postext.dev/cookbook ────────
// Postext measures text with the faces the browser has loaded, and caches the
// widths, so every face must be ready before the first build. Faces come from
// Fontsource: the same static files the PDF embeds, so screen and PDF agree.

/** faces = { 'Family Name': ['400', '400i', '700'] }. `text` is the sample:
 *  letters beyond Latin-1 (č, ł, ő…) also load the latin-ext files. With
 *  `optional`, a face Fontsource does not ship is skipped instead of failing.
 *  Resolves to the number of faces added. */
async function loadFonts(faces, text = '', { optional = false } = {}) {
  kitStatus('Loading fonts…');
  const ranges = {
    latin: 'U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,'
      + 'U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD',
    'latin-ext': 'U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,'
      + 'U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF',
  };
  const subsets = /[Ā-˿Ḁ-ỿ]/.test(text) ? ['latin', 'latin-ext'] : ['latin'];
  const jobs = [];
  let added = 0;
  for (const [family, specs] of Object.entries(faces)) {
    const id = fontsourceId(family);
    const meta = optional ? await fontsourceMeta(family) : null;
    for (const spec of new Set(specs)) {
      const weight = parseInt(spec, 10);
      const style = spec.endsWith('i') ? 'italic' : 'normal';
      if (hasFace(family, weight, style)) continue;
      if (optional && !(meta?.weights.includes(weight) && meta.styles.includes(style))) continue;
      for (const subset of subsets) {
        const url = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${id}-${subset}-${weight}-${style}.woff2`;
        const face = new FontFace(family, `url(${url}) format('woff2')`,
          { weight: String(weight), style, unicodeRange: ranges[subset] });
        jobs.push(face.load().then((ready) => { document.fonts.add(ready); added++; }, () => {
          if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        }));
      }
    }
  }
  await Promise.all(jobs).catch((error) => { kitFail(error); throw error; });
  return added;
}

/** Runs `build` (a buildDocument or buildBundle call) and checks the faces
 *  the pages use. A regular face missing from FONTS is loaded with a warning;
 *  bold and italic variants are loaded when the family ships them. Then the
 *  measurement caches are cleared and the build runs again. */
async function buildWithFonts(build, text = '') {
  const tried = new Set();
  for (let round = 0; round < 3; round++) {
    kitStatus('Laying out…');
    await new Promise(requestAnimationFrame);          // let the status paint first
    const result = await Promise.resolve().then(build).catch((error) => { kitFail(error); throw error; });
    const wanted = { base: {}, variants: {} };
    for (const { font, base } of [result].flat().flatMap(fontStringsOf)) {
      const { family, weight, style } = parseFont(font);
      const key = `${family}|${weight}|${style}`;
      if (tried.has(key) || hasFace(family, weight, style)) continue;
      tried.add(key);
      (wanted[base ? 'base' : 'variants'][family] ??= []).push(`${weight}${style === 'italic' ? 'i' : ''}`);
    }
    if (Object.keys(wanted.base).length) {
      console.warn(`[cookbook] FONTS does not list ${JSON.stringify(wanted.base)}: loading them.`);
    }
    const added = await loadFonts(wanted.base, text) + await loadFonts(wanted.variants, text, { optional: true });
    if (added === 0) return result;
    clearMeasurementCache();
  }
  throw new Error('The fonts did not settle after three builds.');
}

/** Every font string of the layout. `base` marks a block's own face; its
 *  bold, italic and bold-italic variants are listed whether or not used. */
function fontStringsOf(doc) {
  const found = new Map();
  const walk = (node) => {
    if (!node || typeof node !== 'object') return;
    if (Array.isArray(node)) { node.forEach(walk); return; }
    for (const [key, value] of Object.entries(node)) {
      if (typeof value === 'string' && /fontString$/i.test(key)) {
        found.set(value, found.get(value) || key === 'fontString');
      } else if (value && typeof value === 'object') walk(value);
    }
  };
  walk(doc.pages);
  walk(doc.blocks);
  return [...found].map(([font, base]) => ({ font, base }));
}

/** '700 37.5px Open Sans' / 'italic 400 13px "Source Serif 4"' → { family, weight, style }.
 *  A string with no weight ('95.8px Young Serif', from a design text) is 400. */
function parseFont(font) {
  const m = /^(?:(italic|oblique)\s+)?(?:small-caps\s+)?(?:(\d+|bold|normal)\s+)?[\d.]+px\s+(.+)$/.exec(font.trim());
  if (!m) throw new Error(`Unexpected font string: ${font}`);
  const weight = m[2] === 'bold' ? 700 : !m[2] || m[2] === 'normal' ? 400 : Number(m[2]);
  return { family: m[3].replace(/^["']|["']$/g, ''), weight, style: m[1] ? 'italic' : 'normal' };
}

/** True when a loaded FontFace covers exactly this family, weight and style
 *  (document.fonts.check() is also true for families nobody declared). */
function hasFace(family, weight, style) {
  for (const face of document.fonts) {
    if (face.status !== 'loaded' || face.style !== style) continue;
    if (face.family.replace(/^["']|["']$/g, '') !== family) continue;
    const [low, high = low] = face.weight.split(' ').map(Number);
    if (weight >= low && weight <= high) return true;
  }
  return false;
}

/** Fontsource's id for a family: 'Source Serif 4' → 'source-serif-4'. */
function fontsourceId(family) { return family.toLowerCase().replace(/\s+/g, '-'); }

/** The weights and styles a family ships ({ weights: [400, 700], styles: ['normal', 'italic'] }), or null. */
function fontsourceMeta(family) {
  fontsourceMeta.cache ??= new Map();
  const id = fontsourceId(family);
  if (!fontsourceMeta.cache.has(id)) {
    fontsourceMeta.cache.set(id, fetch(`https://api.fontsource.org/v1/fonts/${id}`)
      .then((res) => (res.ok ? res.json() : null), () => null));
  }
  return fontsourceMeta.cache.get(id);
}

// ─── Kit · viewer v1 ── the same in every recipe · postext.dev/cookbook ───────
/** Shows the pages as facing spreads on a dark desk: the first page is a
 *  recto on its own, then verso | recto pairs, as in a bound book. Pages
 *  are painted when they scroll near the screen. */
function showPages(docs, { title, width = 460 } = {}) {
  const root = viewer(title);
  const pages = [docs].flat().flatMap((doc) =>
    doc.pages.map((page) => ({ doc, page, n: (doc.pageIndexOffset ?? 0) + page.index })));
  const spreads = [];
  let verso = null;
  for (const p of pages) {
    if (p.n % 2 === 1) { if (verso) spreads.push([verso, null]); verso = p; }
    else { spreads.push([verso, p]); verso = null; }
  }
  if (verso) spreads.push([verso, null]);
  const density = Math.min(window.devicePixelRatio || 1, 2);
  showPages.painter?.disconnect();
  const painter = new IntersectionObserver((entries) => {
    for (const { isIntersecting, target } of entries) {
      if (!isIntersecting) continue;
      painter.unobserve(target);
      const { doc, page } = target.postext;
      renderPageToCanvas(page, doc, target, { scale: (width * density) / page.width });
    }
  }, { rootMargin: '800px' });
  showPages.painter = painter;
  root.replaceChildren(...spreads.map((pair) => {
    const spread = document.createElement('div');
    spread.className = 'pt-spread';
    for (const p of pair) {
      const figure = document.createElement('figure');
      if (p) {
        const label = p.page.pageLabel || String(p.n + 1);
        const canvas = document.createElement('canvas');
        canvas.postext = p;
        canvas.style.aspectRatio = `${p.page.width} / ${p.page.height}`;
        canvas.setAttribute('role', 'img');
        canvas.setAttribute('aria-label', `Page ${label}`);
        const folio = document.createElement('figcaption');
        folio.textContent = label;
        figure.append(canvas, folio);
        painter.observe(canvas);
      } else figure.className = 'pt-blank';
      spread.append(figure);
    }
    return spread;
  }));
  kitStatus(`${pages.length} ${pages.length === 1 ? 'page' : 'pages'}`);
  document.documentElement.dataset.postext = 'ready';
  return pages.length;
}

/** The desk, the bar and the error reporting, created once. */
function viewer(title) {
  if (!document.getElementById('pt-kit')) {
    document.head.insertAdjacentHTML('beforeend', `<style id="pt-kit">
      :root { color-scheme: dark; }
      body { margin: 0; background: #0e1014; color: #b9bcc4; font: 13px/1.45 system-ui, sans-serif; }
      #pt-bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; align-items: center;
        gap: 6px 16px; padding: 10px 16px; background: rgb(14 16 20 / .92); backdrop-filter: blur(6px);
        border-bottom: 1px solid #23262d; }
      #pt-bar strong { color: #f4f1ea; font-weight: 600; }
      #pt-actions { display: flex; gap: 12px; margin-left: auto; }
      #pt-actions a, #pt-actions button { color: #d8a21a; font: inherit; background: none; border: 0; padding: 0; cursor: pointer; }
      #pages { display: grid; justify-items: center; gap: 48px; padding: 32px 16px 72px; }
      .pt-spread { display: flex; }
      .pt-spread figure { margin: 0; width: min(460px, 44vw); }
      .pt-spread canvas { display: block; width: 100%; background: #fff;
        box-shadow: 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figure:first-child canvas { box-shadow: inset -14px 0 14px -14px rgb(0 0 0 / .18), 0 1px 2px rgb(0 0 0 / .5), 0 22px 44px -16px rgb(0 0 0 / .8); }
      .pt-spread figcaption { margin-top: 10px; text-align: center; font: 600 10px/1 system-ui, sans-serif;
        letter-spacing: .18em; text-transform: uppercase; color: #6c7079; }
      .pt-blank { visibility: hidden; }
      @media (max-width: 760px) {
        .pt-spread { flex-direction: column; gap: 32px; }
        .pt-spread figure { width: min(460px, 92vw); }
        .pt-blank { display: none; }
      }
    </style>`);
    document.body.insertAdjacentHTML('afterbegin',
      '<header id="pt-bar"><strong id="pt-title"></strong><span id="pt-status" role="status"></span><span id="pt-actions"></span></header>');
    document.getElementById('pt-title').textContent = document.title || 'Postext';
    addEventListener('error', (event) => kitFail(event.error ?? event.message));
    addEventListener('unhandledrejection', (event) => kitFail(event.reason));
  }
  if (title) document.getElementById('pt-title').textContent = title;
  return document.getElementById('pages')
    ?? document.body.appendChild(Object.assign(document.createElement('main'), { id: 'pages' }));
}

function kitStatus(text) {
  viewer();
  document.getElementById('pt-status').textContent = text;
}

function kitFail(error) {
  document.documentElement.dataset.postext = 'error';
  kitStatus(`Error: ${error?.message ?? error}`);
}

// ─── Kit · images v1 ── recipes with pictures · postext.dev/cookbook ──────────
/** Registers a photo or PNG for the canvas and keeps its bytes for the PDF.
 *  fetch → ImageBitmap never taints the canvas (a plain cross-origin <img> would). */
async function loadImage(fileId, url) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`Image not found (${res.status}): ${url}`);
  const bytes = new Uint8Array(await res.arrayBuffer());
  registerResourceImage(fileId, await createImageBitmap(new Blob([bytes])));
  (loadImage.bytes ??= new Map()).set(fileId, bytes);
}

/** Registers SVG markup (drawn in code, or fetched) as a vector image. */
async function loadSvg(fileId, svg) {
  const img = new Image();
  img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
  await img.decode();
  registerResourceImage(fileId, img);
  (loadImage.bytes ??= new Map()).set(fileId, new TextEncoder().encode(svg));
}

/** renderToPdf({ resourceBytes: imageBytes }) */
function imageBytes(fileId) { return loadImage.bytes?.get(fileId); }

/** renderToHtml({ resourceImageUrl: imageUrl }) */
function imageUrl(fileId) {
  const bytes = imageBytes(fileId);
  if (!bytes) return undefined;
  imageUrl.urls ??= new Map();
  if (!imageUrl.urls.has(fileId)) {
    const type = /\.svg$/i.test(fileId) ? 'image/svg+xml' : /\.png$/i.test(fileId) ? 'image/png' : 'image/jpeg';
    imageUrl.urls.set(fileId, URL.createObjectURL(new Blob([bytes], { type })));
  }
  return imageUrl.urls.get(fileId);
}

// ─── /Kit ───────────────────────────────────────────────────────────────────────

The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗

Variations

#Let the headings take the whole gap

Both free lines on page 3 then go above The Saltings and the roofs, and none after the list.

-const balancing = { maxLinesPerHeading: 1 }; // one line per heading; the next lever takes more
+const balancing = {}; // the default: up to 4 lines above each heading

#Switch the balancing off

The right column of page 3 then ends two lines short. On page 5 the left column runs to 12 lines and the right to 9, and the statement starts a line lower.

-const balancing = { maxLinesPerHeading: 1 }; // one line per heading; the next lever takes more
+const balancing = { enabled: false };

Pitfalls

Pitfall

avoidWidows guards the foot of a column, avoidOrphans its head

Postext names the two lone lines its own way: avoidWidows (widowMinLines, widowPenalty) keeps a paragraph's first line from standing alone at the foot of a column, and avoidOrphans (orphanMinLines, orphanPenalty) keeps its last line from standing alone at the head of the next. Many style manuals give the two names the other way round, so pick the setting by where it acts. Both are on by default and work as penalties: the layout weighs each one against the empty lines that obeying it would leave. Widows, orphans and runts →

Pitfall

Merged cells need hiddenBy placeholders: use mergeCells

Cells are laid out by their position in the row array, so a merged cell needs placeholder cells marked hiddenBy where it spreads; leaving them out, as HTML does, shifts every later column. Build merges with mergeCells. Tables from data →

Pitfall

Text inside an SVG <img> cannot use web fonts

An SVG is drawn as an image, and an image has no access to the page's web fonts, so its labels fall back to a system face. Outline the text, embed an @font-face subset in the SVG, or move the labels to the caption. Figures and tables as resources →

Pitfall

A swapped palette misses design elements and the reference colour

postext 1.4.1 reads colorPalette into the text styles (body, headings, lists, captions, tables, boxes) but not into the elements of headers, footers, openers and part pages, nor into bodyText.referenceColor: they keep the hex written beside their paletteId. When you swap the palette, for a dark screen edition or a retint, rewrite every linked colour from colorPalette before the build. Semantic colour palette →

Pitfall

A design text's lineHeight is a multiple, never a dimension

In a design slot, a text element's lineHeight multiplies its font size (lineHeight: 1.05). In postext 1.4.1 a dimension such as pt(15) is not rejected: the opener's height measures as NaN, the room it reserves, minHeight included, is dropped without a warning and the text runs under the title. Text, rules and boxes in page designs →

Pitfall

Any headings object switches off the H1 page break

By default an H1 breaks to a recto (always-odd), but passing any headings object resets that default, so chapters run on and span: 'page' does nothing. Restate headings.levels[0].breakBefore: { enabled: true, parity } in every config. Chapters that open on a recto →

Pitfall

Load every face before layout

Layout measures text with the faces the browser has loaded and caches the widths, so a face that arrives after the first build leaves wrong line breaks and a PDF that no longer matches the screen. Load every weight and style first, and call clearMeasurementCache() before rebuilding when one arrives late. Fonts before layout →

When the columns of a closing page differ by one line they stay as they are, the left column a line longer, as a compositor would set them; the trailing cut acts only on a difference of two lines or more. To end the two together, lengthen or shorten the copy by a line.
Postext 1.4.1 trims trailing whitespace in table cells, the no-break space included. To line up positive figures with the costs in brackets, the pen ends each positive figure with a no-break space and a word joiner (U+2060).

Credits

Recipe: Ignacio Ferro
Text: Original prose, CC BY 4.0
Fonts: Brygada 1918 (SIL OFL 1.1) · Epilogue (SIL OFL 1.1) · Spline Sans Mono (SIL OFL 1.1) · Mrs Saint Delafield (SIL OFL 1.1)
Code: MIT, like Postext

Edit this write-up ↗Recipe folder on GitHub ↗

#What you'll build

#The short answer

#Ingredients

#Method

#1 · Keep every line on the grid and let the levers close the gaps

#2 · Cut the text level above a box that crosses the page

#3 · Float a box to the head of the next page

#4 · Give each section its colour without a divider page

#5 · Build the tables from the data, and close the last page level

#The whole recipe

#Variations

#Let the headings take the whole gap

#Switch the balancing off

#Pitfalls

#Credits

More from the Cookbook

Newspaper front page

A book page on a baseline grid

Datasheet: tables from data, merged headers

What you'll build

The short answer

Ingredients

Method

The whole recipe

Variations

Pitfalls

Credits