En bref

Un court manuel pour dimensionner les panneaux solaires et les batteries d’une cabane. Quand le chapitre 3 renvoie à un tableau du chapitre 1, ou le chapitre 1 à une section du chapitre 2, le bon numéro et la page s’impriment, en liens.

Ce que vous allez composer

Un court manuel technique, Power for a Cabin, composé en IBM Plex sur une page de 178 × 233 mm : une couverture avec les trajectoires du soleil dessinées en code, une page de table des matières et trois chapitres sous une bande bleu nuit. Le livre dimensionne une petite installation solaire : chaque chapitre s’appuie donc sur les autres. Le chapitre 3 cite le tableau des consommations du chapitre 1 et le graphique d’ensoleillement du chapitre 2 ; le chapitre 1 envoie le lecteur en avant, à la section 2.3, et en donne la page. L’auteur écrit @tbl:loads et @sec:array-size, comme les lit pandoc-crossref, dans quatre fichiers Markdown distincts. buildBundle les met en page comme un seul livre : chaque renvoi imprime le numéro que la cible a reçu dans son propre chapitre, la page où elle est tombée et un lien vers elle.

Cette recette répond à

Comment renvoyer à une figure, un tableau ou une section d’un autre chapitre, à la manière de pandoc-crossref, en gardant les numéros justes ?
Comment renvoyer à une section et à la page où elle se trouve, et garder les deux justes quand le livre change ?

La réponse courte

script.js · lignes 44–61dans le code complet

// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));

Ingrédients

Fonctionnalités: Renvois Légendes numérotées Livres construits chapitre par chapitre Titres numérotés Table des matières Ouvertures composées Attributs de titre Styles de titre Chapitres non numérotés Titres courants et folios Couvertures, pages de titre et colophons Images dans les maquettes de page Marges en miroir Palette de couleurs sémantique Styles de paragraphe Export PDF
Utilise aussi: Citations dans un style bibliographique Des citations qui placent les figures Figure et Tableau dans votre langue Titres courants selon le rôle de la page Polices intégrées au PDF Types de ressource personnalisés Figures et tableaux comme ressources Titres courants par section Tableaux à partir de données
Typographie: IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
Ressources: Aucune : chaque image est dessinée en code
API: buildBundledecompressWoff2defaultResourceTypesinlineSvgFontsparseTSVprepareFontsregisterResourceImagerenderPageToCanvasrenderToPdfsetAlignmentwithLoadedFonts

Préparation

#1 · Nommer chaque cible une fois, pour tout le livre

Le code est dans la réponse courte plus haut. Les titres prennent un identifiant Pandoc avec son préfixe, ## Sizing the array {#sec:array-size}. Les figures et les tableaux sont des ressources déclarées dans le script, et leurs identifiants s’écrivent de la même façon, fig:sun et tbl:loads : le texte écrit @fig:sun, que la figure soit deux paragraphes plus loin ou deux chapitres plus tôt. Un identifiant doit être unique dans tout le livre, pas seulement dans son chapitre.

#2 · Mettre en page les chapitres comme un seul livre

script.js · lignes 44–61dans le code complet

// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));

buildBundle reporte les compteurs de figures et de tableaux d’un chapitre à l’autre : le premier tableau du chapitre 3 est le 3.1, et @tbl:loads dans le chapitre 3 imprime toujours table 1.1. Un chapitre dont le texte nomme un titre qu’il ne contient pas est mis en page avec le plan de tout le livre, puis remis en page (trois passes au plus) jusqu’à ce que les pages de ce plan ne bougent plus. C’est ainsi que le chapitre 1 peut imprimer section 2.1 … p. 6 avant que le chapitre 2 n’existe sur le papier.

#3 · Choisir les mots qu’imprime un renvoi

crossRefs règle chapter, section et p. (en espagnol capítulo, apartado et pág.). Un renvoi vers une figure ou un tableau imprime le shortLabel de son type, ici en minuscules comme les compose pandoc-crossref, fig. 2.1 et table 1.1. Une capitale dans le préfixe, @Tbl:loads ou @Sec:array, met une capitale au libellé en début de phrase, et [-@tbl:losses] imprime le numéro seul pour tables 2.1 and 3.1.

#4 · Renvoyer en avant aux sections, en arrière aux figures

Une figure ou un tableau est numéroté, et placé en flottant, là où il est cité pour la première fois. @fig:soc dans le chapitre 1 en ferait la figure 1.2 et la placerait dans le chapitre 1. Le chapitre 1 renvoie donc en avant à @sec:autonomy, et les figures et les tableaux sont cités d’abord dans leur propre chapitre ; chaque chapitre suivant y renvoie ensuite librement. Une page accompagne la section, :ref{id="sec:sun-hours" style=page} : un renvoi vers une ressource imprime son libellé et son numéro, jamais sa page.

#5 · Les ouvertures et la couverture viennent de la même bande

script.js · lignes 65–85dans le code complet

const BAND = 52; // mm from the trim's top
const opener = { enabled: true, minHeight: mm(54), slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(BAND + 3) } } },
  { kind: 'text', id: 'kicker', content: t({ en: 'Chapter', es: 'Capítulo' }), ...caps(8.5),
    color: col('sun'), placement: at('container', 'top-left', 0, 2) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(30), lineHeight: 1.05, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#kicker', 'below', 0, 3), size: { width: mm(MEASURE - 26) } } },
  { kind: 'text', id: 'number', content: '{chapterNumber}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(84), lineHeight: 1, color: col('sun'), align: 'right',
    placement: { ...at('container', 'top-right', 0, -6), size: { width: mm(40) } } },
  { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: SERIF, italic: true,
    fontSize: pt(11), lineHeight: 1.38, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: { ...at('container', 'top-left', 0, BAND - MARGIN.top + 8),
      size: { width: mm(MEASURE - 10) } } },
] } };
// The contents page wears the same band, with the book's subtitle as its kicker.
const contentsOpener = { ...opener, minHeight: mm(BAND - MARGIN.top + 4), slot: { elements:
  opener.slot.elements.filter((e) => ['band', 'kicker', 'title'].includes(e.id))
    .map((e) => (e.id === 'kicker' ? { ...e, content: '{subtitle}' } : e)) } };

La bande descend à 55 mm du haut du format sur chaque chapitre et sur la page de table des matières, qui reprennent les mêmes éléments ; le numéro de chapitre est {chapterNumber}, le chapeau un attribut du titre.

script.js · lignes 89–109dans le code complet

const COVER_BAND = 168; // mm
const cover = { enabled: true, slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(COVER_BAND) } } },
  { kind: 'image', id: 'art', resourceId: 'cover',
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill' } } },
  // Stacked upwards from the subtitle, so a title of one line or two keeps its distance.
  { kind: 'text', id: 'subtitle', content: '{subtitle}', fontFamily: SERIF, italic: true,
    fontSize: pt(14), color: col('tint'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND - 22) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(52), lineHeight: 1, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#subtitle', 'above', 0, -4), size: { width: mm(140) } } },
  { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...caps(8.5), color: col('sun'),
    placement: at('#title', 'above', 0, -4) },
  { kind: 'text', id: 'author', content: '{author}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(13), color: col('ink'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND + 14) },
  { kind: 'text', id: 'edition', content: '{attr.edition}', ...caps(7.5), color: col('muted'),
    placement: at('#author', 'below', 0, 2.5) },
] } };

La recette complète

Sandbox

// ═══ Postext Cookbook · Nº 094 · A technical book whose references cross chapters ═══
// https://postext.dev/en/cookbook/technical-book-crossref-chapters
// Code: MIT · Text: original (CC BY 4.0) · Charts: generated in code (CC BY 4.0)
// Fonts: IBM Plex Serif, Sans Condensed and Mono (SIL OFL 1.1) · Needs postext ≥ 1.28.0
// A small handbook in four Markdown documents. The text writes @fig:sun, @tbl:loads and
// @sec:array-size the way pandoc-crossref reads them, and buildBundle resolves each one to
// the right number, title or page wherever in the book its target lies.
import {
  buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
  defaultResourceTypes, parseTSV, setAlignment, inlineSvgFonts,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'technical-book-crossref-chapters';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a night-blue band, one burnt-orange accent, an amber for the charts
const palette = {
  ink: '#1c1f24', // text: a cool near-black
  night: '#1f3247', // openers, the cover, table heads
  accent: '#a8471a', // numbers, kickers, references (5.6:1 on paper)
  sun: '#e9a33a', // the charts and the cover only, never text on paper
  tint: '#f5ede3', // daylight in the charts
  rule: '#cfc7bc', // hairlines
  muted: '#5e636a', // running heads, colophon, chart labels
  paper: '#ffffff',
};
// Each colour names its palette entry and carries its hex.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.accent })
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const SERIF = 'IBM Plex Serif', COND = 'IBM Plex Sans Condensed', MONO = 'IBM Plex Mono';
const TRIM = { w: 178, h: 233 }; // mm: a technical-book trim
const MARGIN = { top: 22, bottom: 22, inner: 20, outer: 32 }; // a 126 mm measure
const LEAD = 13.8; // pt: the body leading
const MEASURE = TRIM.w - MARGIN.inner - MARGIN.outer;
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const caps = (size, extra = {}) => ({ fontFamily: MONO, fontSize: pt(size), fontWeight: 600,
  letterSpacing: pt(size * 0.14), textTransform: 'uppercase', align: 'left', ...extra });

// #region answer: one set of identifiers for the whole book, resolved across chapters
// buildBundle lays the chapters out in order. Each chapter whose text names a target it
// does not hold (`@sec:array-size` in chapter 1, `@tbl:loads` in chapter 3) is laid out
// with the outline of the whole book, so the reference prints "section 2.3" and its page,
// and links to it. Headings carry their ids in the Markdown, `## Sizing the array
// {#sec:array-size}`; figures and tables are resources whose ids are what follows the @.
const book = () => buildBundle({ chapters, config: config(), resources });
const crossRefs = {
  chapter: t({ en: 'chapter {n}', es: 'capítulo {n}' }), // @sec:array → "chapter 2"
  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
  page: t({ en: 'p. {n}', es: 'pág. {n}' }), // :ref{id="sec:losses" style=page} → "p. 7"
};
// Figures and tables count per chapter ({h1}.{n}) and carry on from one document to the
// next. A reference prints the type's shortLabel: @fig:sun → "Fig. 2.1", @Tbl:loads (capital
// T, at the start of a sentence) → "Table 1.1", [-@tbl:loads] → the bare "1.1".
const resourceTypes = defaultResourceTypes(LANG).map((type) => ({ ...type,
  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
    : t({ en: 'fig.', es: 'figura' }),
  ...(type.id === 'table' && { captionStyle: { position: 'above' } }) }));
// #endregion

// #region opener: each chapter under a night-blue band, its number large on the outer side
const BAND = 52; // mm from the trim's top
const opener = { enabled: true, minHeight: mm(54), slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(BAND + 3) } } },
  { kind: 'text', id: 'kicker', content: t({ en: 'Chapter', es: 'Capítulo' }), ...caps(8.5),
    color: col('sun'), placement: at('container', 'top-left', 0, 2) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(30), lineHeight: 1.05, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#kicker', 'below', 0, 3), size: { width: mm(MEASURE - 26) } } },
  { kind: 'text', id: 'number', content: '{chapterNumber}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(84), lineHeight: 1, color: col('sun'), align: 'right',
    placement: { ...at('container', 'top-right', 0, -6), size: { width: mm(40) } } },
  { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: SERIF, italic: true,
    fontSize: pt(11), lineHeight: 1.38, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: { ...at('container', 'top-left', 0, BAND - MARGIN.top + 8),
      size: { width: mm(MEASURE - 10) } } },
] } };
// The contents page wears the same band, with the book's subtitle as its kicker.
const contentsOpener = { ...opener, minHeight: mm(BAND - MARGIN.top + 4), slot: { elements:
  opener.slot.elements.filter((e) => ['band', 'kicker', 'title'].includes(e.id))
    .map((e) => (e.id === 'kicker' ? { ...e, content: '{subtitle}' } : e)) } };
// #endregion

// #region cover: the sun's December and June paths over the panels, the title in the band
const COVER_BAND = 168; // mm
const cover = { enabled: true, slot: { elements: [
  { kind: 'box', id: 'band', style: { backgroundColor: col('night') },
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(COVER_BAND) } } },
  { kind: 'image', id: 'art', resourceId: 'cover',
    placement: { ...at('bleed', 'top-left'), size: { width: 'fill' } } },
  // Stacked upwards from the subtitle, so a title of one line or two keeps its distance.
  { kind: 'text', id: 'subtitle', content: '{subtitle}', fontFamily: SERIF, italic: true,
    fontSize: pt(14), color: col('tint'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND - 22) },
  { kind: 'text', id: 'title', content: '{titleText}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(52), lineHeight: 1, color: col('paper'), align: 'left', overflow: 'wrap',
    placement: { ...at('#subtitle', 'above', 0, -4), size: { width: mm(140) } } },
  { kind: 'text', id: 'kicker', content: '{attr.kicker}', ...caps(8.5), color: col('sun'),
    placement: at('#title', 'above', 0, -4) },
  { kind: 'text', id: 'author', content: '{author}', fontFamily: COND, fontWeight: 600,
    fontSize: pt(13), color: col('ink'), align: 'left',
    placement: at('page', 'top-left', MARGIN.inner, COVER_BAND + 14) },
  { kind: 'text', id: 'edition', content: '{attr.edition}', ...caps(7.5), color: col('muted'),
    placement: at('#author', 'below', 0, 2.5) },
] } };
// #endregion

// #region running-heads: the book on the verso, the chapter on the recto, folios in orange
const head = (id, content, parity, edge, x, extra = {}) => ({ kind: 'text', id, content,
  parity, pages: 'body', ...caps(7), color: col('muted'), placement: at('page', edge, x, 12),
  ...extra });
const folio = { color: col('accent'), fontSize: pt(8) };
const header = { elements: [
  head('verso-folio', '{pageNumber}', 'even', 'top-left', MARGIN.outer, folio),
  head('verso-title', '{title}', 'even', 'top-left', MARGIN.outer + 9),
  head('recto-title', '{chapterTitle}', 'odd', 'top-right', -(MARGIN.outer + 9),
    { align: 'right' }),
  head('recto-folio', '{pageNumber}', 'odd', 'top-right', -MARGIN.outer,
    { ...folio, align: 'right' }),
] };
const footer = { elements: [head('drop-folio', '{pageNumber}', 'all', 'top', 0,
  { ...folio, pages: 'opener', align: 'center', placement: at('container', 'bottom', 0, 8) })] };
const bare = { header: { elements: [] }, footer: { elements: [] } };
// #endregion

const contents = { // what :::toc prints: chapters in the condensed face, sections under them
  levels: [
    { level: 1, fontFamily: COND, fontSize: pt(13), fontWeight: 600, lineHeight: pt(18),
      numberFontFamily: MONO, numberFontSize: pt(10), numberFontWeight: 600,
      numberColor: col('accent'), numberWidth: mm(9), numberGap: mm(2), marginTop: pt(10) },
    { level: 2, fontFamily: SERIF, fontSize: pt(9.5), lineHeight: pt(13.5), indent: mm(11),
      numberFontFamily: MONO, numberFontSize: pt(8), numberColor: col('muted'),
      numberWidth: mm(9), numberGap: mm(2) },
  ],
  pageNumber: { fontFamily: MONO, fontSize: pt(8.5), fontWeight: 600, width: mm(8) },
  leader: { char: '. ', gap: mm(2) },
};

const config = () => ({
  locale: t({ en: 'en-gb', es: 'es' }), // British patterns for the English edition
  crossRefs, resourceTypes, colorPalette, toc: contents, header, footer,
  page: { sizePreset: 'custom', width: mm(TRIM.w), height: mm(TRIM.h), dpi: 150,
    margins: { top: mm(MARGIN.top), bottom: mm(MARGIN.bottom), left: mm(MARGIN.inner),
      right: mm(MARGIN.outer), mirror: true } },
  layout: { layoutType: 'single' },
  bodyText: { fontFamily: SERIF, fontSize: pt(9.6), lineHeight: pt(LEAD), color: col('ink'),
    boldColor: col('ink'), italicColor: col('ink'),
    referenceColor: col('accent'), // every reference is a link: orange says so
    textAlign: 'justify', firstLineIndent: mm(4.5), indentAfterHeading: false,
    hyphenation: { enabled: true }, optimalLineBreaking: true,
    avoidWidows: true, avoidOrphans: true, avoidRunts: true },
  // 'remainder': a section title that opens a page keeps the half line above it, so its
  // text follows it as closely as under the titles set in mid-page (a book in one column).
  headings: { fontFamily: COND, color: col('ink'), fontWeight: 600,
    columnHeadSpace: 'remainder', levels: [
    // 'any': short chapters start on the next page, recto or verso.
    { level: 1, fontSize: pt(30), numberingTemplate: '{1}',
      breakBefore: { enabled: true, parity: 'any' }, advancedDesign: opener,
      marginBottom: pt(0) },
    { level: 2, fontSize: pt(13), lineHeight: pt(LEAD * 1.5), numberingTemplate: '{1}.{2}',
      numberSeparator: '   ', marginTop: pt(LEAD / 2), marginBottom: pt(0) },
  ] },
  // The cover and the contents take no number and no contents line, so the first
  // chapter is still chapter 1.
  headingStyles: [
    { id: 'cover', numbered: false, toc: false, advancedDesign: cover, ...bare },
    { id: 'contents', numbered: false, toc: false, advancedDesign: contentsOpener, ...bare },
  ],
  paragraphStyles: [
    { id: 'formula', fontFamily: MONO, fontSize: pt(9), textAlign: 'center',
      firstLineIndent: pt(0), marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 2) },
    { id: 'colophon', fontFamily: COND, fontSize: pt(7.5), lineHeight: pt(10.5),
      color: col('muted'), textAlign: 'left', firstLineIndent: pt(0), spaceBetween: pt(4),
      marginTop: pt(LEAD * 3) },
  ],
  tableStyle: { rules: 'horizontal', borderColor: col('rule'), borderWidth: pt(0.5),
    headerBackground: col('night'), headerColor: col('paper'), headerFontFamily: COND,
    headerFontSize: pt(8.2), bodyFontFamily: COND, bodyFontSize: pt(8.6),
    bodyColor: col('ink'), cellPadding: mm(1.4) },
  captionStyle: { fontFamily: COND, fontSize: pt(8.4), color: col('ink'),
    labelBold: true, labelColor: col('accent'), gap: mm(2.5) },
});

// ─── 2 · Content ────────────────────────────────────────────────────────────
const front = String.raw`---
Exemple Markdown · 16 lignes · content.en.md
title: "Power for a Cabin"
subtitle: "Sizing a small off-grid solar system"
author: "Lucía Arregui"
---

# Power for a Cabin {style="cover" kicker="Larch Hill Technical Notes · No. 4" edition="Second edition"}

# Contents {style="contents"}

:::toc

:::paragraphs{style="colophon"}
Larch Hill Technical Notes are short handbooks for people who build and maintain their own equipment. The cabin, the valley and the figures in this one are an example worked by hand: check every number against your own loads, site and suppliers before you buy anything.

Set in IBM Plex Serif, IBM Plex Sans Condensed and IBM Plex Mono (SIL OFL). Text written for the Postext Cookbook, CC BY 4.0.
:::
`; // frontmatter, cover and contents (content.<lang>.md)
const load = String.raw`# The daily load {#sec:load lead="Every component of an off-grid system is sized from one number: the energy the cabin uses on a winter day. Get it wrong and nothing downstream can put it right."}
Exemple Markdown · 26 lignes · content.load.en.md

A solar system for a cabin is sized backwards. You start at the sockets, add up what the cabin draws in a day, and only then work out how many panels and batteries it takes to supply that much in the worst month of the year. This chapter arrives at that number: 1,159 watt-hours a day, which the rest of the book rounds to 1,160. @Sec:array turns it into panels, and @sec:battery into batteries.

The example is a stone cabin of 48 m² at 1,100 m in a valley that faces south-east, used every weekend and for three weeks in winter. Heating and cooking are wood and bottled gas; electricity runs the lights, a fridge, a water pump, a laptop and a router.

## Listing the loads {#sec:load-list}

Walk round the cabin with a notebook and write down everything that plugs in or is wired in, with its power in watts and the hours it runs on a winter day. The power is on the rating plate or in the manual; for anything with a motor or a compressor, a plug-in meter left for a day gives a truer figure than the plate. @Tbl:loads is the list for the example cabin.

Two lines in the table are easy to forget. The inverter, which turns the battery’s 24 volts into 230 volts for the sockets, draws 8 W from the moment it is switched on, whether anything is plugged in or not: over a day that is more than the lights. The router runs all night as well. Both are worth a timer or a switch by the door, and the saving is worked out in @sec:winter-margin.

The fridge figure needs care. A chest fridge of 100 litres draws 55 W while its compressor runs, and in a cool cabin the compressor runs about five hours in twenty-four. In August it may run nine, but August is not the month that sizes the system, as @sec:sun-hours shows on :ref{id="sec:sun-hours" style=page}.

## When the energy is used {#sec:load-profile}

The total says how much energy the cabin needs; it does not say when. @Fig:profile spreads the same 1,160 Wh over the hours of a winter day. The fridge, the router and the inverter make a floor of about 27 W that never goes away. The laptop adds a block in the morning, and the evening brings the largest draw of the day, when lights, the stove fan and the pump run together after sunset.

That evening peak matters more than its size suggests. Almost all of it falls after the sun has gone, so none of it can come straight from the panels: it is drawn from the battery and paid back the next day. The battery bank in @sec:autonomy is sized for exactly this, and for the days when the sun does not pay it back at all.

## The winter margin {#sec:winter-margin}

A list made in October is a guess about January. Lights run longer in midwinter, guests come at New Year, and someone always brings a hair dryer. Rather than pad every line of @tbl:loads, keep the list honest and add the margin once, at the end, where it can be seen.

For a weekend cabin a margin of 15% is enough, and the example takes it from the loads themselves rather than adding it on top: switching the inverter and the router off at night saves 8 W and 8 W for ten hours, 160 Wh a day, close to 14% of the total. The system is sized for the full 1,160 Wh, and the habit of the switch by the door is the margin.

With the load fixed, the next question is how much of it the sun can supply in the darkest month. That is the work of @sec:array, which starts from the sun hours of the site on :ref{id="sec:sun-hours" style=page}.
`; // chapter 1: content.load.<lang>.md
const array = String.raw`# The array {#sec:array lead="Panels are sized for December, when the days are short and the sun is low. In summer the same array makes twice what the cabin needs, and that is the price of a winter that works."}
Exemple Markdown · 26 lignes · content.array.en.md

@Sec:load ended with a daily load of 1,160 Wh, the total of @tbl:loads. This chapter finds the array that delivers that much on an average December day, after every loss between the panel and the socket.

## Sun hours by month {#sec:sun-hours}

The sunlight a site receives is given in peak sun hours: the number of hours at a standard intensity of 1,000 W/m² that would deliver the same energy as the whole day does. A panel rated at 300 W makes roughly 300 Wh for each peak sun hour, before losses. The figures come from a solar database for the site’s coordinates and the panels’ tilt; @fig:sun gives them for the example cabin, at 42° N with the panels tilted at 60°.

A steep tilt trades some summer yield for the low winter sun. Even so, December gets half the yield of July: 2.8 peak sun hours against 5.6. December is therefore the design month, and every calculation in this chapter uses its figure.

## Losses between panel and socket {#sec:losses}

Not all of the energy a panel makes reaches the sockets. Each stage between them takes a share, and the shares multiply. @Tbl:losses lists them for the example system.

The largest single loss is the inverter’s, and it applies only to the loads that run on 230 V. In a cabin where the fridge, the pump and the lights all run on 24 V, the overall factor rises from 0.79 to about 0.85. The example keeps the inverter in the chain, because the laptop and the router need it and the calculation is safer that way. The battery’s share is its round-trip loss, the energy that goes in and does not come out; it is small for lithium cells and larger for lead-acid, as @sec:chemistry explains on :ref{id="sec:chemistry" style=page}.

## Sizing the array {#sec:array-size}

The array must make the daily load, divided by the overall loss factor, in the peak sun hours of December:

:::paragraphs{style="formula"}
1,160 Wh ÷ (2.8 h × 0.79) = 524 W
:::

The example uses two panels of 310 W in series, 620 W in all, which leaves a margin of 18% for an old panel, a cloudy fortnight or a load that has grown.

The panels work between ten and four; the cabin, as @fig:profile shows, spends most of its energy after dark. How large the battery between them must be is the subject of @sec:battery.
`; // chapter 2
const battery = String.raw`# The battery bank {#sec:battery lead="The battery carries the cabin through every night and through the grey days when the panels make almost nothing. Its size is a choice about how many such days in a row you will accept."}
Exemple Markdown · 26 lignes · content.battery.en.md

The array of @sec:array-size works between ten and four, the cabin mostly after dark, and on an overcast December day the 2.8 peak sun hours of @fig:sun fall to half an hour or less. The battery bank bridges both gaps.

## Days of autonomy {#sec:autonomy}

Autonomy is the number of days the bank can run the cabin with no sun at all. Three days is usual for a cabin in a valley with fog, and it is what the example uses:

:::paragraphs{style="formula"}
3 days × 1,160 Wh = 3,480 Wh usable
:::

The daily load is the total of @tbl:loads, without the margin of @sec:winter-margin (:ref{id="sec:winter-margin" style=page}), which stays in reserve. How far a bank may be drawn down depends on its chemistry.

## Choosing a chemistry {#sec:chemistry}

@Tbl:chemistry compares the three chemistries on sale for small off-grid systems. Lithium iron phosphate (LiFePO4) cells can be drawn down to 20% every night for thousands of cycles. Lead-acid batteries last longest when they are never taken below half their charge, so the same usable energy needs a bank about 60% larger, and five times the weight to carry up the track.

The round trip matters too. The overall factor of 0.79 in @tbl:losses assumes the lithium bank’s 0.95. With an AGM bank at 0.85 the factor falls to 0.71, and the formula of @sec:array-size asks for 586 W instead of 524 W. The two 310 W panels still cover it, with a margin of 6% instead of 18%. Change the battery, and tables [-@tbl:losses] and [-@tbl:chemistry] must be read again together.

The example cabin uses a LiFePO4 bank of 200 Ah at 25.6 V: 5.1 kWh nominal, 4.1 kWh usable, a little more than three days.

## A week of cloud {#sec:cloud-week}

@Fig:soc follows the bank’s state of charge through five December days: one clear, three overcast at about half a peak sun hour, and a clear day to finish. The bank starts at 80%, rises to 94% on the first afternoon and then loses about 17% a day, with a dip each evening from the peak of @fig:profile. At its lowest, on the last night of cloud, it holds 27%, above the 20% floor.

The figure also shows the weakness of sizing for the average December day. On a clear day the array makes about 1,370 Wh after losses, only 210 Wh more than the cabin uses, so a bank drawn down by three grey days takes some twelve clear days to fill again. A third panel, on a controller of its own, raises the surplus of a clear day from 210 Wh to about 900 Wh; a small petrol generator with a charger refills the bank in an afternoon.
`; // chapter 3
const tables = String.raw`Load	Power (W)	Hours a day	Wh a day
Exemple Markdown · 22 lignes · content.tables.en.md
LED lighting, 6 points	30	5	150
Chest fridge, 100 L	55	5	275
Water pump, 24 V	120	0.5	60
Laptop	45	4	180
Router	8	24	192
Inverter, idle draw	8	24	192
Two phones	10	2	20
Wood-stove fan	15	6	90
**Total**			**1,159**

Between panel and socket	Factor
Dust, snow and shading	0.95
Cable resistance	0.97
MPPT charge controller	0.97
Battery round trip (LiFePO4)	0.95
Inverter, 230 V loads	0.93
**Overall (product)**	**0.79**

Chemistry	Usable depth	Round trip	Cycles	Bank for 3 days	Mass
LiFePO4	80%	0.95	4,000	200 Ah, 5.1 kWh	45 kg
AGM lead-acid	50%	0.85	600	300 Ah, 7.2 kWh	220 kg
Tubular lead-acid	50%	0.80	1,500	300 Ah, 7.2 kWh	260 kg
`; // the three tables as TSV, blank-line separated
// Four Markdown documents in reading order, one book.
const chapters = [front, load, array, battery].map((markdown) => ({ markdown }));

// #region tables: three tables pasted from a spreadsheet as TSV, parsed into table models
function tableModel(tsv, columnWidths) {
  let m = Object.assign(parseTSV(tsv), { headerRowCount: 1, columnWidths });
  for (let r = 0; r < m.rows.length; r++) { // figures flush right, words flush left
    for (let c = 1; c < m.rows[r].length; c++) m = setAlignment(m, { row: r, col: c }, 'right');
  }
  return m;
}
const [loads, losses, chemistry] = tables.trim().split(/\n\s*\n/);
const TABLES = { loads, losses, chemistry };
// #endregion
const CAPTIONS = t({ en: {
  loads: 'Daily loads of the example cabin on a winter day',
  losses: 'Losses between the panels and the sockets, multiplied',
  chemistry: 'Three battery chemistries for 3,480 Wh of usable energy',
  profile: 'Average draw, hour by hour, on a winter day. Grey: the constant floor of fridge, '
    + 'router and inverter; orange: everything else; pale band: daylight.',
  sun: 'Peak sun hours a day by month at 42°\u00a0N, panels tilted at 60°. December is the '
    + 'design month.',
  soc: 'State of charge of the 5.1 kWh bank over five December days: clear, three overcast, '
    + 'clear. Shaded: night. Dashed: the 20% floor.',
}, es: {
  loads: 'Consumos diarios de la cabaña de ejemplo en un día de invierno',
  losses: 'Pérdidas entre los paneles y los enchufes, multiplicadas',
  chemistry: 'Tres químicas de batería para 3480\u00a0Wh de energía útil',
  profile: 'Consumo medio, hora a hora, en un día de invierno. Gris: el suelo constante de '
    + 'frigorífico, rúter e inversor; naranja: todo lo demás; banda clara: horas de luz.',
  sun: 'Horas de sol pico al día por mes a 42°\u00a0N, con los paneles inclinados 60°. Diciembre '
    + 'es el mes de diseño.',
  soc: 'Estado de carga del banco de 5,1 kWh durante cinco días de diciembre: despejado, tres '
    + 'nublados, despejado. Sombreado: noche. Discontinua: el suelo del 20\u00a0%.',
} });
const table = (id, widths) => ({ id: `tbl:${id}`, typeId: 'table', kind: 'table',
  caption: CAPTIONS[id], createdAt: 0, updatedAt: 0,
  table: { model: tableModel(TABLES[id], widths) } });
const figure = (id, [w, h]) => ({ id: `fig:${id}`, typeId: 'figure', kind: 'svg',
  caption: CAPTIONS[id], altText: CAPTIONS[id], createdAt: 0, updatedAt: 0,
  svg: { fileId: `${id}.svg`, width: w * 10, height: h * 10 } });
const resources = [
  { id: 'cover', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0,
    svg: { fileId: 'cover.svg', width: TRIM.w * 10, height: 110 * 10 } },
  figure('profile', [MEASURE, 50]), figure('sun', [MEASURE, 46]), figure('soc', [MEASURE, 50]),
  table('loads', [44, 18, 18, 18]), table('losses', [70, 20]),
  table('chemistry', [25, 15, 19, 12, 24, 12]),
];

// #region art: the cover and three charts, drawn in code in the book's palette
// The charts name their label face in a style rule, and loadSvg embeds its Fontsource file.
const LABELS = `text{font-family:'IBM Plex Mono';font-size:2.5px;fill:${palette.muted}}`;
const n2 = (v) => +v.toFixed(2);
const sheet = (w, h, body, style = '') => `<svg xmlns="http://www.w3.org/2000/svg" `
  + `width="${w * 10}" height="${h * 10}" viewBox="0 0 ${w} ${h}"><style>${style}</style>`
  + `${body}</svg>`;
const rect = (x, y, w, h, fill, extra = '') => `<rect x="${n2(x)}" y="${n2(y)}" width="${n2(w)}" `
  + `height="${n2(h)}" fill="${palette[fill]}" ${extra}/>`;
const pathOf = (pts) => pts.map(([x, y]) => `${n2(x)} ${n2(y)}`).join('L');
const line = (pts, stroke, width, extra = '') => `<path d="M${pathOf(pts)}" fill="none" `
  + `stroke="${palette[stroke]}" stroke-width="${width}" ${extra}/>`;
const label = (x, y, text, anchor = 'middle') => `<text x="${n2(x)}" y="${n2(y)}" `
  + `text-anchor="${anchor}">${text}</text>`;
// A chart frame: plot area from x0 to w − 2, y from top 3 to the axis at h − 7.
function axes(w, h, x0, max, step, unit) {
  const y = (v) => h - 7 - (v / max) * (h - 10);
  let out = '';
  for (let v = 0; v <= max; v += step) {
    out += line([[x0, y(v)], [w - 2, y(v)]], 'rule', v ? 0.15 : 0.35)
      + label(x0 - 1.5, y(v) + 0.9, `${v}${v === max ? unit : ''}`, 'end');
  }
  return { out, y };
}
// The hourly profile of chapter 1, built from the same loads as its table.
const FLOOR = 27.46; // W: fridge 275 Wh + router + inverter 192 Wh each, over 24 hours
const EXTRA = Array.from({ length: 24 }, (_, h) => (h >= 18 && h <= 22 ? 30 : 0) // lights
  + (h === 7 || h === 19 ? 30 : 0) + (h >= 9 && h <= 12 ? 45 : 0) // pump, laptop
  + (h === 21 || h === 22 ? 10 : 0) + (h >= 17 && h <= 22 ? 15 : 0)); // phones, stove fan
function profileArt(w, h) {
  const x0 = 12, bw = (w - 2 - x0) / 24;
  const { out, y } = axes(w, h, x0, 120, 30, ' W');
  let bars = rect(x0 + 8.5 * bw, 3, 9.25 * bw, h - 10, 'tint') + out; // daylight, 8:30 to 17:45
  EXTRA.forEach((extra, i) => {
    const x = x0 + i * bw + 0.35;
    bars += rect(x, y(FLOOR), bw - 0.7, y(0) - y(FLOOR), 'rule')
      + (extra ? rect(x, y(FLOOR + extra), bw - 0.7, y(FLOOR) - y(FLOOR + extra), 'accent') : '');
  });
  const hours = [0, 6, 12, 18, 24].map((hr) => label(x0 + hr * bw, h - 2.5, `${hr}h`)).join('');
  return bars + hours;
}
const PSH = [3.1, 3.9, 4.6, 5.0, 5.2, 5.3, 5.6, 5.6, 5.2, 4.3, 3.3, 2.8]; // peak sun hours
const MONTHS = t({ en: 'JFMAMJJASOND', es: 'EFMAMJJASOND' });
function sunArt(w, h) {
  const x0 = 12, bw = (w - 2 - x0) / 12;
  const { out, y } = axes(w, h, x0, 6, 1, ' h');
  const value = (v) => (LANG === 'es' ? v.toFixed(1).replace('.', ',') : v.toFixed(1));
  return out + PSH.map((v, i) => rect(x0 + i * bw + 1.6, y(v), bw - 3.2, y(0) - y(v),
    i === 11 ? 'accent' : 'night') + label(x0 + (i + 0.5) * bw, y(v) - 1.2, value(v))
    + label(x0 + (i + 0.5) * bw, h - 2.5, MONTHS[i])).join('');
}
// Five December days, hour by hour: the array (620 W × 0.79) against the load profile.
function socSeries() {
  const bank = 5120, days = [2.8, 0.5, 0.4, 0.7, 2.8];
  const sun = Array.from({ length: 24 }, (_, h) => (h >= 8 && h < 17
    ? Math.sin(Math.PI * (h - 7.5) / 9) : 0));
  const sum = sun.reduce((a, b) => a + b);
  let soc = 0.8 * bank;
  const out = [0.8];
  days.forEach((d) => sun.forEach((s, h) => {
    soc = Math.min(bank, soc + d * 620 * 0.79 * s / sum - FLOOR - EXTRA[h]);
    out.push(soc / bank);
  }));
  return out;
}
function socArt(w, h) {
  const x0 = 12, step = (w - 2 - x0) / 120;
  const { out, y } = axes(w, h, x0, 100, 20, t({ en: '%', es: ' %' }));
  let night = '';
  for (let d = 0; d < 5; d++) {
    night += rect(x0 + d * 24 * step, 3, 8.5 * step, h - 10, 'tint')
      + rect(x0 + (d * 24 + 17.75) * step, 3, 6.25 * step, h - 10, 'tint')
      + label(x0 + (d * 24 + 12) * step, h - 2.5, t({ en: `day ${d + 1}`, es: `día ${d + 1}` }));
  }
  const curve = line(socSeries().map((v, i) => [x0 + i * step, y(v * 100)]), 'accent', 0.6,
    'stroke-linejoin="round"');
  return night + out + line([[x0, y(20)], [w - 2, y(20)]], 'night', 0.35,
    'stroke-dasharray="1.2 0.8"') + curve;
}
// The cover: the sun's paths in June and December over a tilted panel, on the night band.
function coverArt(w, h) {
  const horizon = 86, cx = w * 0.56;
  const path = (r, k) => line(Array.from({ length: 41 }, (_, i) => {
    const a = Math.PI * (i / 40);
    return [cx - r * Math.cos(a), horizon - k * r * Math.sin(a)];
  }), 'sun', 0.5);
  const sunAt = (r, k, color, size) => `<circle cx="${n2(cx)}" cy="${n2(horizon - k * r)}" `
    + `r="${size}" fill="${palette[color]}"/>`;
  let cells = ''; // a panel tilted towards the low sun, 6 × 4 cells
  const px = 14, py = 84, pw = 46, ph = 30, skew = 14;
  for (let r = 0; r < 4; r++) {
    for (let c = 0; c < 6; c++) {
      const [x, y] = [px + c * pw / 6 + (r + 0.5) * skew / 4, py - (r + 1) * ph / 4];
      const pts = [[x, y], [x + pw / 6 - 0.8, y], [x + pw / 6 - 0.8 + skew / 4 * 0.8,
        y - ph / 4 + 0.8], [x + skew / 4 * 0.8, y - ph / 4 + 0.8]].map(([a, b]) => [a, b + ph / 4]);
      cells += `<path d="M${pts.map(([a, b]) => `${n2(a)} ${n2(b)}`).join('L')}Z" `
        + `fill="${palette.paper}" fill-opacity="${0.16 + ((r + c) % 3) * 0.05}"/>`;
    }
  }
  return path(70, 0.9) + path(54, 0.45) + sunAt(70, 0.9, 'sun', 2.2) + sunAt(54, 0.45, 'sun', 4)
    + line([[8, horizon], [w - 8, horizon]], 'sun', 0.35) + cells;
}
// #endregion

// ─── 3 · Fonts ──────────────────────────────────────────────────────────────
// Every face the design uses.
const FONTS = {
  'IBM Plex Serif': ['400', '400i', '600'],
  'IBM Plex Sans Condensed': ['400', '600', '700'],
  'IBM Plex Mono': ['400', '600', '700'],
};

// ─── 4 · Build & show ───────────────────────────────────────────────────────
const text = chapters.map((chapter) => chapter.markdown).join('\n');
await prepareFonts(text, config(), kitFonts(FONTS));
await loadSvg('cover.svg', sheet(TRIM.w, 110, coverArt(TRIM.w, 110)));
await loadSvg('profile.svg', sheet(MEASURE, 50, profileArt(MEASURE, 50), LABELS));
await loadSvg('sun.svg', sheet(MEASURE, 46, sunArt(MEASURE, 46), LABELS));
await loadSvg('soc.svg', sheet(MEASURE, 50, socArt(MEASURE, 50), LABELS));
// One VDTDocument per Markdown document.
const docs = await withLoadedFonts(book, { ...kitFonts(FONTS), text });
showPages(docs, { title: t({ en: 'Power for a Cabin', es: 'Energía para una cabaña' }) });
// One PDF for the book: a reference in chapter 3 links to its table in chapter 1.
offerPdf(() => renderToPdf(docs, { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);

Kit · core, fonts, viewer, pdf, images : identique dans toutes les recettes · 315 lignes
// ─── 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 v3 ── the same in every recipe · postext.dev/cookbook
// Postext loads the faces a config asks for before layout (prepareFonts,
// buildDocumentWithFonts) and asks the kit for the files: Fontsource's, the
// files the PDF embeds too.

/** The options of buildDocumentWithFonts / prepareFonts / withLoadedFonts:
 *  the Fontsource resolver, and the faces of FONTS loaded with the ones the
 *  config names. FONTS = { 'Family Name': ['400', '400i', '700'] }. */
function kitFonts(FONTS = {}) {
  const faces = Object.entries(FONTS).flatMap(([family, specs]) => specs.map((spec) =>
    ({ family, weight: parseInt(spec, 10), style: spec.endsWith('i') ? 'italic' : 'normal' })));
  return { resolve: fontsourceResolver, faces };
}

/** A face's Fontsource files, in a fixed order: latin, then latin-ext and greek
 *  when `text` needs them and the family ships them (kitSubsetsFor), each with
 *  its unicode-range. Null for a weight or slant Fontsource does not ship. */
async function fontsourceResolver(family, weight, style, { text = '' } = {}) {
  const id = fontsourceId(family);
  const meta = await fontsourceMeta(family);
  if (meta && !(meta.weights.includes(weight) && meta.styles.includes(style))) return null;
  kitStatus('Loading fonts…');
  const at = await fontsourceAt(id);
  return ['latin', ...kitSubsetsFor(text, meta)].map((subset) => ({
    source: `${at}files/${id}-${subset}-${weight}-${style}.woff2`,
    unicodeRange: kitRanges()[subset],
  }));
}

/** The unicode-range of each Fontsource file the kit loads (a function: the
 *  kit is inlined after the pen's code, which runs before a const would be set). */
function kitRanges() {
  return {
    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',
    greek: 'U+0370-03FF',
  };
}

/** For the cjk, arabic and comics blocks, which add their own files: the
 *  faces of `faces` = { 'Family Name': ['400', '400i', '700'] }. `text` is the sample:
 *  č ł † α χ also load latin-ext and greek files (kitSubsetsFor). With
 *  `optional`, a face Fontsource does not ship is skipped instead of failing.
 *  The files are added once all have loaded, in the order asked (latin, then
 *  latin-ext, then greek), whatever order they arrive in: the last one added
 *  wins a character two files hold. Resolves to the number of faces added. */
async function loadFonts(faces, text = '', { optional = false } = {}) {
  kitStatus('Loading fonts…');
  const ranges = kitRanges();
  const jobs = [];
  for (const [family, specs] of Object.entries(faces)) {
    const id = fontsourceId(family);
    const todo = [...new Set(specs)].map((spec) => [parseInt(spec, 10), spec.endsWith('i') ? 'italic' : 'normal'])
      .filter(([weight, style]) => !hasFace(family, weight, style)); // before any await
    const at = fontsourceAt(id);
    const meta = optional || /[^\0-ÿ]/u.test(text) ? await fontsourceMeta(family) : null;
    const subsets = ['latin', ...kitSubsetsFor(text, meta)];
    for (const [weight, style] of todo) {
      if (optional && !(meta?.weights.includes(weight) && meta.styles.includes(style))) continue;
      for (const subset of subsets) {
        const url = `${await at}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().catch(() => {
          if (subset === 'latin' && !optional) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        }));
      }
    }
  }
  const ready = await Promise.all(jobs).catch((error) => { kitFail(error); throw error; });
  return ready.filter((face) => face && document.fonts.add(face)).length;
}

/** A loaded FontFace covers this family, weight and style (fonts.check() would
 *  also say yes 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;
}

/** The files beyond latin `text` needs that `meta`'s family ships. */
function kitSubsetsFor(text, meta) {
  return [[/[Ā-˿ᴀ-ᶿḀ-ỿ†ℓⱠ-Ɀ꜠-ꟿ]/u, 'latin-ext'], [/[Ͱ-Ͽ]/u, 'greek']]
    .filter(([re, x]) => re.test(text) && meta?.subsets?.includes(x)).map(([, x]) => x);
}

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

/** A package's folder at the one version @5 names now (#766). */
function fontsourceAt(id, u = `https://cdn.jsdelivr.net/npm/@fontsource/${id}@`) {
  return (fontsourceAt.c ??= {})[id] ??= fetch(u + '5/package.json').then((r) => r.json())
    .then((p) => p.version || 5, () => 5).then((v) => `${u}${v}/`);
}

/** The family's Fontsource metadata (weights, styles, subsets), 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 v2 ── the same in every recipe · postext.dev/cookbook
/** The pages as spreads on a dark desk, page 1 alone, then verso | recto,
 *  each painted when it scrolls near. Other options go to renderPageToCanvas. */
function showPages(docs, { title, width = 460, ...render } = {}) {
  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, { ...render, 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 · pdf v3 ── the same in every recipe that exports a PDF
/** The Fontsource files the screen used, as TrueType, with their range and
 *  place: the nearest weight the family ships, upright with no italic;
 *  latin, then what its letters need (kitSubsetsFor). */
async function fontsourceProvider(family, weight, style, request) {
  const id = fontsourceId(family);
  const meta = await fontsourceMeta(family);
  const weights = meta?.weights?.length ? meta.weights : [400, 700];
  const w = weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a));
  const s = style === 'italic' && meta && !meta.styles.includes('italic') ? 'normal' : style;
  const text = String.fromCodePoint(...(request?.codePoints ?? []));
  const files = await Promise.all(['latin', ...kitSubsetsFor(text, meta)].map(async (subset, order) => {
    const res = await fetch(`${await fontsourceAt(id)}files/${id}-${subset}-${w}-${s}.woff2`);
    if (!res.ok) throw new Error(`Fontsource has no ${family} ${w} ${s} ${subset}`);
    return Object.assign(await decompressWoff2(new Uint8Array(await res.arrayBuffer())),
      { unicodeRange: kitRanges()[subset], order });
  }));
  return files.length === 1 ? files[0] : files;
}

/** A "Build the PDF" button; then "Open the PDF" (a new tab: CodePen's frame
 *  shows no PDFs) and a download link. */
function offerPdf(makePdf, filename) {
  viewer();
  const button = Object.assign(document.createElement('button'), { type: 'button', textContent: 'Build the PDF' });
  button.dataset.postextPdf = filename;
  button.addEventListener('click', async () => {
    button.disabled = true;
    button.textContent = 'Building the PDF…';
    try {
      const bytes = await makePdf();
      const url = URL.createObjectURL(new Blob([bytes], { type: 'application/pdf' }));
      const size = `${Math.max(1, Math.round(bytes.length / 1024))} KB`;
      button.replaceWith(
        Object.assign(document.createElement('a'), { href: url, target: '_blank', rel: 'noopener', textContent: 'Open the PDF ↗' }),
        Object.assign(document.createElement('a'), { href: url, download: filename, textContent: `Download ${filename} · ${size}` }));
    } catch (error) {
      button.disabled = false;
      button.textContent = 'Build the PDF';
      kitFail(error);
    }
  });
  document.getElementById('pt-actions').append(button);
}

// ─── Kit · images v3 ── 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 as a vector image, its fonts inside (inlineSvgFonts, ≥ 1.25).
 *  `options` go to registerResourceImage: { singleInk: true } tints it on the canvas. */
async function loadSvg(fileId, svg, options) {
  if (typeof inlineSvgFonts === 'function') svg = await inlineSvgFonts(svg, svgFaces);
  const img = new Image();
  img.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
  await img.decode();
  registerResourceImage(fileId, img, options);
  (loadImage.bytes ??= new Map()).set(fileId, new TextEncoder().encode(svg));
}

/** A face's Fontsource files: nearest weight; latin + what the SVG sets. */
async function svgFaces(family, weight, style, { codePoints = [] } = {}) {
  const [id, m] = [fontsourceId(family), await fontsourceMeta(family)];
  const w = m?.weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a)) ?? weight;
  const s = m?.styles.includes(style) === false ? 'normal' : style;
  return Promise.all(['latin', ...kitSubsetsFor(String.fromCodePoint(...codePoints), m)].map(async (x) => new Uint8Array(
    await (await fetch(`${await fontsourceAt(id)}files/${id}-${x}-${w}-${s}.woff2`)).arrayBuffer())));
}

/** 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 ───────────────────────────────────────────────────────────────────────

Le script.js composé s’exécute tel quel : collez-le dans le script de module de n’importe quelle page, ou ouvrez la recette sur CodePen. Dossier de la recette sur GitHub ↗ (s’ouvre dans un nouvel onglet)

Variantes

#Imprimer « Figure 2.1 » dans le texte

Un livre qui écrit ses renvois en toutes lettres utilise le nom complet du type au lieu du libellé court.

-  shortLabel: type.id === 'table' ? t({ en: 'table', es: 'tabla' })
-    : t({ en: 'fig.', es: 'figura' }),
+  shortLabel: type.id === 'table' ? t({ en: 'Table', es: 'Tabla' })
+    : t({ en: 'Figure', es: 'Figura' }),

#Numéroter les sections avec un signe de paragraphe

-  section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
+  section: '§ {n}',

Erreurs fréquentes

Erreur fréquente

Une figure est numérotée et placée là où elle est citée pour la première fois

Le premier renvoi :ref ou @fig: à une figure ou à un tableau lui donne son numéro et sa place : un renvoi dans un chapitre antérieur l’y attire. Renvoyez en avant à la section qui la contient, et à la figure elle-même seulement une fois qu’elle est placée. Renvois →

Un renvoi vers un identifiant qu’aucun chapitre ne définit imprime ?. Vérifiez les identifiants après avoir renommé un titre dans un chapitre : les renvois qui y mènent se trouvent dans les autres.
Mettre en page les chapitres un par un avec buildDocument perd à la fois les compteurs et le plan du livre : chaque chapitre renumérote ses figures à partir de 1 et un renvoi vers un autre chapitre imprime ?. Utilisez buildBundle, ou enchaînez continuation et passez outline vous-même.
Les équations n’ont pas de numérotation propre dans Postext : @eq: ne trouve qu’une ancre que vous posez et imprime son texte ; ce livre écrit ses deux formules sans numéro.
Un titre de section qui ouvre une page, ou qui se trouve sous un tableau placé en tête de page comme le 3.3 en page 9, perd par défaut tout son espace au-dessus, et le calage sur la grille place alors la fraction de ligne dont il a besoin sous le titre, plus loin de son texte que les titres en milieu de page. headings.columnHeadSpace: 'remainder' garde cette fraction de ligne au-dessus du titre (titres). Ce réglage convient à un livre sur une colonne, où aucune colonne voisine ne montre que le titre commence un peu plus bas.

Crédits

Recette: Ignacio Ferro
Texte: Texte original, CC BY 4.0
Polices: IBM Plex Serif (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1) · IBM Plex Mono (SIL OFL 1.1)
Code: MIT, comme Postext

Modifier ce texte ↗ (s’ouvre dans un nouvel onglet)Dossier de la recette sur GitHub ↗ (s’ouvre dans un nouvel onglet)

En bref

#Ce que vous allez composer

#La réponse courte

#Ingrédients

#Préparation

#1 · Nommer chaque cible une fois, pour tout le livre

#2 · Mettre en page les chapitres comme un seul livre

#3 · Choisir les mots qu’imprime un renvoi

#4 · Renvoyer en avant aux sections, en arrière aux figures

#5 · Les ouvertures et la couverture viennent de la même bande

#La recette complète

#Variantes

#Imprimer « Figure 2.1 » dans le texte

#Numéroter les sections avec un signe de paragraphe

#Erreurs fréquentes

#Crédits

Autres recettes

Un livre à partir de chapitres séparés

Ouvrage collectif avec une bibliographie par chapitre

Un manuel dont les renvois indiquent la page