In short
A short owner's manual for a touring bicycle. When the text sends you to another section, it gives that section's number and the page it is on, and both are links.
What you'll build
The owner's manual of a fictional touring bicycle, the Ardena T3: four A5 pages set in Archivo, with the model name in a navy band over the first page. A manual is read out of order, so every instruction that depends on another one says where it is: see section 3.2 on page 3. The writer names a heading, a paragraph or a phrase in a step with an identifier and writes :ref wherever the text points to it; Postext prints the number, the title or the page and makes it a link. The contents list on the cover is written the same way, so moving a section, or translating the manual and letting it reflow, never leaves a stale number.
This recipe answers
- How do I refer to a section and the page it is on, and keep both right when the book changes?
The short answer
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };
The words a reference prints, and references that are links
Ingredients
- Features
- Cross-referencesNumbered headingsBullet lists and checklistsNumbered listsCallout boxesDesigned openersHeading attributesRunning heads and foliosMirrored marginsSemantic colour palettePDF export
- Type
- Archivo, Archivo Narrow (SIL OFL 1.1)
- Assets
- None: every picture is drawn in code
Method
#1 · Name what the text points to
The code is the short answer above. Headings take a Pandoc identifier, ### Checking pad wear {#sec-pad-wear}; the warning about tyre pressure starts with :anchor{#warn-pressure}, an invisible mark; the last step of fitting a wheel is [close the lever so that it points backwards]{#step-close-lever}, which keeps its words and names them; and the box opens with :::callout{#box-wet type="note" title="Wet weather"}. A reference to the step prints the step's words, a reference to the box its title.
#2 · One target, four ways to name it
:ref{id="sec-pad-wear"} prints section 3.2 with the word from crossRefs.section; style=page prints page 3 with the word from crossRefs.page; style=title prints Checking pad wear; style=pageNumber prints the bare 3. The cover's contents list combines the bare number, the title and the bare page, so it reads like a table of contents. In Spanish the same references print apartado 3.2 and página 3, because the templates follow the edition's language.
#3 · The pages settle on their own
A page number is only known once the manual is laid out. The engine lays it out, reads the page each target landed on and lays it out again until no reference changes, the same loop that fills a table of contents. Text that grows in translation, or a section moved to the front, changes the pages and the references follow them, forward and back.
#4 · The numbers come from the level-2 counter
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: ' ', fontFamily: DISPLAY,
fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: ' ', fontFamily: DISPLAY,
fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };
The manual has one level-1 heading, the model name on the cover, so its sections number from level 2: {2} gives 1 to 5 and {2}.{3} gives 1.1, 1.2.
#5 · The cover is the opener of that heading
const BAND = 104; // mm from the trim's top
const label = { fontFamily: DISPLAY, fontWeight: 700, textTransform: 'uppercase',
letterSpacing: pt(1.6), align: 'left' };
const cover = {
enabled: true,
minHeight: mm(BAND - PAGE.top + 8), // the contents start 8 mm under the band
slot: { elements: [
{ kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
placement: { ...at('page', 'top-left'), size: { width: 'fill', height: mm(BAND) } } },
{ kind: 'box', id: 'stripe', style: { backgroundColor: col('orange') },
placement: { ...at('page', 'top-left', 0, BAND), size: { width: 'fill', height: mm(2.5) } } },
{ kind: 'text', id: 'kicker', content: '{attr.kicker}', ...label, fontSize: pt(9),
color: col('tint'), placement: at('container', 'top-left', 0, 6) },
{ kind: 'text', id: 'title', content: '{titleText}', fontFamily: DISPLAY, fontWeight: 700,
fontSize: pt(58), lineHeight: 1, color: col('paper'), align: 'left',
placement: at('container', 'top-left', -1, 30) },
{ kind: 'text', id: 'subtitle', content: '{attr.subtitle}', fontFamily: TEXT,
fontSize: pt(11), color: col('paper'), align: 'left',
placement: at('container', 'top-left', 0, 55) },
{ kind: 'text', id: 'edition', content: '{attr.edition}', ...label, fontSize: pt(7.5),
color: col('tint'), placement: at('container', 'top-left', 0, 74) },
] },
};
The band is 104 mm deep, half the page, and an orange stripe closes it. The kicker, subtitle and edition line are attributes of the heading, so the Spanish edition changes them in its own text.
const palette = {
ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
The whole recipe
// ═══ Postext Cookbook · Nº 092 · A manual whose references point to pages ══════════
// https://postext.dev/en/cookbook/manual-see-page-references
// Code: MIT · Text: original (CC BY 4.0) · Pictures: none
// Fonts: Archivo, Archivo Narrow (SIL OFL 1.1) · Needs postext ≥ 1.28.0
import { buildDocumentWithFonts, renderPageToCanvas } 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 = 'manual-see-page-references';
// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a navy cover band and one signal orange for numbers and references
const palette = {
ink: '#1b1f24', navy: '#1d2c3c', orange: '#b8471b', tint: '#f7e7de', rule: '#d5cfc8',
muted: '#5c636b', paper: '#ffffff',
};
// Each colour carries its hex and the palette entry it follows.
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = Object.entries({ ...palette, 'main-color': palette.orange })
.map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
// #endregion
const TEXT = 'Archivo', DISPLAY = 'Archivo Narrow';
const PAGE = { w: 148, h: 210, top: 20, bottom: 20, inner: 18, outer: 15 }; // mm: A5, mirrored
const LEAD = 13; // pt
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
// #region answer: the words a reference prints, and references that are links
// In the Markdown, `## Brakes {#sec-brakes}` names a heading, `:anchor{#warn-pressure}`
// a point in a paragraph and `[close the lever]{#step-close-lever}` a phrase in a step.
// `:ref{id="sec-pad-wear"}` prints "section 3.2", `style=page` "page 3", `style=title`
// the heading's words and `style=pageNumber` the bare 3. The page numbers come from the
// previous layout pass: the engine lays the manual out again until they hold.
const crossRefs = {
section: t({ en: 'section {n}', es: 'apartado {n}' }), // H2 and H3: "section 3.2"
page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
};
// Every reference is a link in the PDF and on screen; this makes it look like one.
const references = { referenceColor: col('orange'), referenceBold: true };
// #endregion
// #region numbers: sections 1–5 and 1.1, 1.2… under the one level-1 heading
const H2 = { level: 2, numberingTemplate: '{2}', numberSeparator: ' ', fontFamily: DISPLAY,
fontWeight: 700, fontSize: pt(15), lineHeight: pt(LEAD * 1.5), color: col('navy'),
marginTop: pt(LEAD), marginBottom: pt(LEAD / 3) };
const H3 = { level: 3, numberingTemplate: '{2}.{3}', numberSeparator: ' ', fontFamily: DISPLAY,
fontWeight: 700, fontSize: pt(10.5), lineHeight: pt(LEAD), color: col('ink'),
marginTop: pt(LEAD / 2), marginBottom: pt(LEAD / 4) };
// #endregion
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 ↗ (opens in a new tab)
Variations
#Say "p." in the references
A reference book with many page references saves room with the abbreviation.
- page: t({ en: 'page {n}', es: 'página {n}' }), // spelt out: a manual is read by anyone
+ page: t({ en: 'p. {n}', es: 'pág. {n}' }),#Leave the references in ink
When most of the page is references, keep them in the text colour and in bold; they are still links in the PDF and on screen.
-const references = { referenceColor: col('orange'), referenceBold: true };
+const references = { referenceColor: col('ink'), referenceBold: true };Pitfalls
- A reference to an
:anchorwith no style prints the page, because an invisible anchor has no words of its own. Use[words]{#id}when the reference should quote the text. - An identifier must be unique in the book. References reach the first
{#sec-brakes}, and the Sandbox's Checks panel lists a second one asduplicateAnchor.
Credits
- Recipe
- Ignacio Ferro
- Text
- Original prose, CC BY 4.0
- Fonts
- Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
Edit this write-up ↗ (opens in a new tab)Recipe folder on GitHub ↗ (opens in a new tab)


