Skip to main content
Recipe number 94

Cookbook · Chapter 5 · Book structure

A technical book whose references cross chapters

A three-chapter solar handbook whose text writes @fig:sun, @tbl:loads and @sec:array-size, and buildBundle prints each number and page across chapters.

  • Trim 178 × 233 mm
  • 1 column
  • IBM Plex Serif 9.6/13.8
  • IBM Plex Mono
  • IBM Plex Sans Condensed
  • 9 pages
  • Level
  • Postext 1.57.1
  • Laid out in 134 ms
  • 246 lines of code

In short

A short handbook on sizing solar panels and batteries for a cabin. When chapter 3 points back to a table in chapter 1, or chapter 1 points ahead to a section in chapter 2, the right number and page are printed, and they are links.

What you'll build

A short technical handbook, Power for a Cabin, set in IBM Plex on a 178 × 233 mm page: a cover with the sun's paths drawn in code, a contents page and three chapters under a night-blue band. The book sizes a small solar system, so each chapter leans on the others. Chapter 3 cites the load table of chapter 1 and the sun-hours chart of chapter 2; chapter 1 sends the reader ahead to section 2.3 and gives its page. The author writes @tbl:loads and @sec:array-size, as pandoc-crossref reads them, in four separate Markdown files. buildBundle lays them out as one book, so every reference prints the number the target got in its own chapter, the page it landed on, and a link to it.

This recipe answers

  • How do I refer to a figure, a table or a section in another chapter, pandoc-crossref style, and keep the numbers right?
  • 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 44–61in full code
// 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' } }) }));

One set of identifiers for the whole book, resolved across chapters

Ingredients

Type
IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
Assets
None: every picture is drawn in code

Method

#1 · Name every target once, for the whole book

The code is the short answer above. Headings take a Pandoc identifier with its prefix, ## Sizing the array {#sec:array-size}. Figures and tables are resources declared in the script, and their ids are written the same way, fig:sun and tbl:loads, so the text reads @fig:sun whether the figure is two paragraphs away or two chapters back. An id must be unique across the book, not only in its chapter.

#2 · Lay the chapters out as one book

script.js · lines 44–61in full code
// 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 carries the figure and table counters from chapter to chapter, so the first table of chapter 3 is 3.1 and @tbl:loads in chapter 3 still prints table 1.1. A chapter whose text names a heading it does not hold is laid out with the outline of the whole book, and laid out again (three rounds at most) until the pages of that outline stop moving. That is how chapter 1 can print section 2.1 … p. 6 before chapter 2 exists on paper.

#3 · Choose the words a reference prints

crossRefs sets chapter, section and p. (in Spanish capítulo, apartado and pág.). A figure or table reference prints its type's shortLabel, here lowercase as pandoc-crossref sets them, fig. 2.1 and table 1.1. A capital in the prefix, @Tbl:loads or @Sec:array, capitalises the label at the start of a sentence, and [-@tbl:losses] prints the bare number for tables 2.1 and 3.1.

#4 · Refer forward to sections, back to figures

A figure or a table is numbered, and floated, where it is first cited. @fig:soc in chapter 1 would make it figure 1.2 and place it in chapter 1. So chapter 1 points ahead to @sec:autonomy, and the figures and tables are cited first in their own chapter; every later chapter refers back to them freely. A page goes with the section, :ref{id="sec:sun-hours" style=page}: a resource reference prints its label and number, never its page.

#5 · The openers and the cover come from the same band

script.js · lines 65–85in full code
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)) } };

The band runs 55 mm from the trim's top on every chapter and on the contents page, which reuse the same elements; the chapter number is {chapterNumber}, the lead a heading attribute.

script.js · lines 89–109in full code
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) },
] } };

The whole recipe

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 @.

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

A book that spells out its references uses the type's full name instead of the short label.

-  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' }),

#Number sections with a paragraph sign

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

Pitfalls

Pitfall

A figure is numbered and placed where it is first cited

The first :ref or @fig: reference to a figure or table gives it its number and its place, so a reference in an earlier chapter pulls it there. Refer forward to the section that holds it, and to the figure itself only once it is placed. Cross-references →

  • A reference to an id that no chapter sets prints ?. Check the ids after renaming a heading in one chapter: the references to it live in the others.
  • Laying the chapters out one by one with buildDocument loses both the counters and the book outline: every chapter numbers its figures from 1 again and a reference to another chapter prints ?. Use buildBundle, or chain continuation and pass outline yourself.
  • Equations have no numbering of their own in Postext, so @eq: finds only an anchor you set and prints its text; this book writes its two formulas without numbers.
  • A section title that opens a page, or stands under a table floated to its head as 3.3 does on page 9, drops its whole space above by default, and the grid snap then puts the part of a line it needs under the title, further from its text than the titles in mid-page. headings.columnHeadSpace: 'remainder' keeps that part of a line above the title (headings). It suits a book in one column, where no column beside it shows that the title starts a little lower.

Credits

Text
Original prose, CC BY 4.0
Fonts
IBM Plex Serif (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1) · IBM Plex Mono (SIL OFL 1.1)
SandboxPDF