Saltar al contingut principal
Recepta número 94

Receptari · Capítol 5 · Estructura del llibre

Un llibre tècnic amb remissions entre capítols

Un manual solar de tres capítols on el text escriu @fig:sun, @tbl:loads i @sec:array-size, i buildBundle imprimeix cada número i pàgina entre capítols.

En aquesta pàgina
Sortida
Canvas · PDF
Nivell
Avançat
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.28.0 · postext-pdf ≥ 1.28.0
Llicència
Actualitzada el 11 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Mostra en castellà: encara no hi ha edició en català
  • Format 178 × 233 mm
  • 1 columna
  • IBM Plex Serif 9,6/13,8
  • IBM Plex Mono
  • IBM Plex Sans Condensed
  • 9 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 119 ms
  • 246 línies de codi

En poques paraules

Un manual breu per calcular els panells i les bateries d'una cabana. Quan el capítol 3 remet a una taula del capítol 1, o el capítol 1 a un apartat del 2, s'imprimeixen el número i la pàgina correctes, i són enllaços.

Què compondràs

Un manual tècnic breu, Energía para una cabaña, compost en IBM Plex sobre una pàgina de 178 × 233 mm: una coberta amb les trajectòries del sol dibuixades en codi, un índex i tres capítols sota una banda blau nit. El llibre dimensiona una instal·lació solar petita, així que cada capítol es recolza en els altres. El capítol 3 cita la taula de consums de l'1 i el gràfic d'hores de sol del 2; el capítol 1 envia el lector a l'apartat 2.3 i li dona la pàgina. Qui escriu posa @tbl:loads i @sec:array-size, tal com els llegeix pandoc-crossref, en quatre fitxers Markdown separats. buildBundle els compon com un sol llibre, així que cada remissió imprimeix el número que va rebre la seva destinació al seu propi capítol, la pàgina on va caure i un enllaç.

Aquesta recepta respon a

  • Com remeto a una figura, una taula o una secció d'un altre capítol, a l'estil de pandoc-crossref, amb els números sempre correctes?
  • Com remeto a una secció i a la pàgina on és, i mantinc totes dues correctes quan el llibre canvia?

La resposta curta

script.js · línies 44–61al codi 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' } }) }));

Ingredients

Tipografia
IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Anomena cada destinació una vegada, per a tot el llibre

El codi és la resposta curta de més amunt. Els títols porten un identificador de Pandoc amb el seu prefix, ## El tamaño del campo {#sec:array-size}. Les figures i les taules són recursos declarats a l'script, i els seus identificadors s'escriuen igual, fig:sun i tbl:loads, de manera que el text diu @fig:sun tant si la figura és dos paràgrafs enrere com dos capítols enrere. Cada identificador ha de ser únic en tot el llibre, no només al seu capítol.

#2 · Compon els capítols com un sol llibre

script.js · línies 44–61al codi 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 arrossega els comptadors de figures i taules d'un capítol al següent, així que la primera taula del capítol 3 és la 3.1 i @tbl:loads al capítol 3 continua imprimint tabla 1.1. Un capítol amb un text que esmenta un títol que no conté es compon amb l'esquema del llibre sencer, i es torna a compondre (tres passades com a màxim) fins que les pàgines d'aquest esquema deixen de moure's. Per això el capítol 1 pot imprimir apartado 2.1 … pág. 6 abans que el capítol 2 existeixi en paper.

#3 · Tria les paraules de cada remissió

crossRefs fixa capítulo, apartado i pág. (en anglès, chapter, section i p.). Una remissió a una figura o una taula imprimeix el shortLabel del seu tipus, aquí en minúscula, figura 2.1 i tabla 1.1, com s'escriuen enmig d'una frase. Una majúscula al prefix, @Tbl:loads o @Sec:array, posa en majúscula l'etiqueta a començament de frase, i [-@tbl:losses] imprimeix només el número per a las tablas 2.1 y 3.1.

#4 · Remet cap endavant a apartats i cap enrere a figures

Una figura o una taula es numera, i es col·loca, on se cita per primera vegada. @fig:soc al capítol 1 la convertiria en la figura 1.2 i la posaria al capítol 1. Per això el capítol 1 remet cap endavant a @sec:autonomy, i cada figura i cada taula se citen primer al seu propi capítol; els capítols següents hi remeten sense problema. La pàgina va amb l'apartat, :ref{id="sec:sun-hours" style=page}: una remissió a un recurs imprimeix la seva etiqueta i el seu número, mai la seva pàgina.

#5 · Les obertures i la coberta surten de la mateixa banda

script.js · línies 65–85al codi 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 banda baixa 55 mm des de la vora superior a cada capítol i a l'índex, que reutilitza els mateixos elements; el número és {chapterNumber} i l'entradeta, un atribut del títol.

script.js · línies 89–109al codi 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 recepta completa

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 = 'es'; // @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 @.

L'script.js compost funciona tal com és: enganxa'l com a script de mòdul en qualsevol pàgina o obre la recepta a CodePen. Carpeta de la recepta a GitHub ↗ (s'obre en una pestanya nova)

Variants

#Escriu «Figura 2.1» al text

Un llibre que escriu completes les seves remissions fa servir el nom del tipus en lloc de l'etiqueta curta.

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

#Numera els apartats amb el signe de paràgraf

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

Errors freqüents

Error freqüent

Una figura es numera i es col·loca on es cita per primer cop

La primera referència :ref o @fig: a una figura o una taula li dona el número i el lloc, de manera que una referència en un capítol anterior la porta allà. Remet cap endavant a la secció que la conté, i a la figura només quan ja estigui col·locada. Referències creuades →

  • Una remissió a un identificador que cap capítol no defineix imprimeix ?. Revisa els identificadors després de canviar el nom d'un títol en un capítol: les remissions que hi apunten són als altres.
  • Compondre els capítols un per un amb buildDocument perd els comptadors i l'esquema del llibre: cada capítol numera les seves figures des d'1 i una remissió a un altre capítol imprimeix ?. Fes servir buildBundle, o encadena continuation i passa tu mateix l'outline.
  • Les equacions no tenen numeració pròpia a Postext, així que @eq: només troba una àncora que hagis posat i n'imprimeix el text; aquest llibre escriu les seves dues fórmules sense número.
  • Un títol d'apartat que obre una pàgina, o que queda sota una taula al cap de la pàgina com el 3.3 a la pàgina 9, perd per defecte tot el seu espai superior, i l'ajust a la retícula posa llavors sota el títol la fracció de línia que li falta: el text queda més lluny que en els títols a mitja pàgina. headings.columnHeadSpace: 'remainder' deixa aquesta fracció de línia sobre el títol (encapçalaments). Convé a un llibre a una columna, on cap columna veïna no delata que el títol comença una mica més avall.

Crèdits

Text
Text original, 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