Skip to main content
Recipe number 92

Cookbook · Chapter 5 · Book structure

A manual whose references point to pages

A bicycle owner's manual whose cross-references say "see section 3.2 on page 3", forward and back, with every number and page taken from the layout.

On this page
  • Trim 148 × 210 mm
  • 1 column
  • Archivo 9.3/13
  • Archivo Narrow
  • 4 pages
  • Level
  • Postext 1.57.1
  • Laid out in 64 ms
  • 131 lines of code

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

script.js · lines 28–38in full code
// 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

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

script.js · lines 42–47in full code
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

script.js · lines 51–73in full code
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.

script.js · lines 13–20in full code
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

Sandbox
// ═══ 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 :anchor with 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 as duplicateAnchor.

Credits

Text
Original prose, CC BY 4.0
Fonts
Archivo (SIL OFL 1.1) · Archivo Narrow (SIL OFL 1.1)
SandboxPDF