En pocas palabras
Un manual breve para calcular los paneles y las baterías de una cabaña. Cuando el capítulo 3 remite a una tabla del capítulo 1, o el capítulo 1 a un apartado del 2, se imprimen el número y la página correctos, y son enlaces.
Lo que vas a componer
Un manual técnico breve, Energía para una cabaña, compuesto en IBM Plex sobre una página de 178 × 233 mm: una cubierta con las trayectorias del sol dibujadas en código, un índice y tres capítulos bajo una banda azul noche. El libro dimensiona una instalación solar pequeña, así que cada capítulo se apoya en los demás. El capítulo 3 cita la tabla de consumos del 1 y el gráfico de horas de sol del 2; el capítulo 1 manda al lector al apartado 2.3 y le da la página. Quien escribe pone @tbl:loads y @sec:array-size, como los lee pandoc-crossref, en cuatro archivos Markdown separados. buildBundle los compone como un solo libro, así que cada remisión imprime el número que recibió su destino en su propio capítulo, la página en que cayó y un enlace.
Esta receta responde a
- ¿Cómo remito a una figura, una tabla o una sección de otro capítulo, al estilo de pandoc-crossref, con los números siempre correctos?
- ¿Cómo remito a una sección y a la página en que está, y mantengo ambas correctas cuando el libro cambia?
La respuesta corta
// 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' } }) }));
Ingredientes
- Funciones
- Referencias cruzadasPies numeradosLibros construidos capítulo a capítuloTítulos numeradosÍndice generalAperturas diseñadasAtributos de títuloEstilos de títuloCapítulos sin númeroCabeceras y foliosCubiertas, portadas y colofonesImágenes en los diseños de páginaMárgenes simétricosPaleta de color semánticaEstilos de párrafoExportación a PDF
- También usa
- Citas en un estilo de citaCitas que colocan las figurasFigura y Tabla en tu idiomaCabeceras según el tipo de páginaFuentes incrustadas en el PDFTipos de recurso propiosFiguras y tablas como recursosCabeceras por secciónTablas a partir de datos
- Tipografía
- IBM Plex Serif, IBM Plex Sans Condensed, IBM Plex Mono (SIL OFL 1.1)
- Recursos
- Ninguno: todas las imágenes se dibujan en código
Elaboración
#1 · Nombra cada destino una vez, para todo el libro
El código es la respuesta corta de arriba. Los títulos llevan un identificador de Pandoc con su prefijo, ## El tamaño del campo {#sec:array-size}. Las figuras y las tablas son recursos declarados en el script, y sus identificadores se escriben igual, fig:sun y tbl:loads, de modo que el texto dice @fig:sun tanto si la figura está dos párrafos atrás como dos capítulos atrás. Cada identificador debe ser único en todo el libro, no solo en su capítulo.
#2 · Compón los capítulos como un solo libro
// 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 arrastra los contadores de figuras y tablas de un capítulo al siguiente, así que la primera tabla del capítulo 3 es la 3.1 y @tbl:loads en el capítulo 3 sigue imprimiendo tabla 1.1. Un capítulo cuyo texto remite a un encabezado que no contiene se compone con el esquema del libro entero, y se vuelve a componer (tres pasadas como mucho) hasta que las páginas de ese esquema dejan de moverse. Por eso el capítulo 1 puede imprimir apartado 2.1 … pág. 6 antes de que el capítulo 2 exista en papel.
#3 · Elige las palabras de cada remisión
crossRefs fija capítulo, apartado y pág. (en inglés, chapter, section y p.). Una remisión a una figura o una tabla imprime el shortLabel de su tipo, aquí en minúscula, figura 2.1 y tabla 1.1, como se escriben en medio de una frase. Una mayúscula en el prefijo, @Tbl:loads o @Sec:array, pone en mayúscula la etiqueta a principio de frase, y [-@tbl:losses] imprime el número solo para las tablas 2.1 y 3.1.
#4 · Remite hacia delante a apartados y hacia atrás a figuras
Una figura o una tabla se numera, y se coloca, donde se cita por primera vez. @fig:soc en el capítulo 1 la convertiría en la figura 1.2 y la pondría en el capítulo 1. Por eso el capítulo 1 remite hacia delante a @sec:autonomy, y cada figura y cada tabla se citan primero en su propio capítulo; los capítulos siguientes remiten a ellas sin problema. La página va con el apartado, :ref{id="sec:sun-hours" style=page}: una remisión a un recurso imprime su etiqueta y su número, nunca su página.
#5 · Las aperturas y la cubierta salen de la misma banda
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 baja 55 mm desde el borde superior en cada capítulo y en el índice, que reutiliza los mismos elementos; el número es {chapterNumber} y la entradilla, un atributo del encabezado.
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 receta completa
// ═══ 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 @.
El script.js compuesto funciona tal cual: pégalo como script de módulo en cualquier página o abre la receta en CodePen. Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)
Variantes
#Escribe «Figura 2.1» en el texto
Un libro que escribe completas sus remisiones usa el nombre del tipo en lugar de la etiqueta corta.
- 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 los apartados con el signo de párrafo
- section: t({ en: 'section {n}', es: 'apartado {n}' }), // @sec:losses → "section 2.2"
+ section: '§ {n}',Errores frecuentes
Error frecuente
Una figura se numera y se coloca donde se cita por primera vez
La primera referencia :ref o @fig: a una figura o una tabla le da su número y su sitio, así que una referencia en un capítulo anterior la lleva allí. Remite hacia delante a la sección que la contiene, y a la figura solo cuando ya esté colocada. Referencias cruzadas →
- Una remisión a un identificador que ningún capítulo define imprime ?. Revisa los identificadores después de renombrar un título en un capítulo: las remisiones a él están en los otros.
- Componer los capítulos uno a uno con
buildDocumentpierde los contadores y el esquema del libro: cada capítulo numera sus figuras desde 1 y una remisión a otro capítulo imprime ?. UsabuildBundle, o encadenacontinuationy pasa tú eloutline. - Las ecuaciones no tienen numeración propia en Postext, así que
@eq:solo encuentra un ancla que hayas puesto e imprime su texto; este libro escribe sus dos fórmulas sin número. - Un título de apartado que abre una página, o que queda bajo una tabla en cabeza de página como el 3.3 en la página 9, pierde por defecto todo su espacio superior, y el ajuste a la rejilla pone entonces bajo el título la fracción de línea que le falta: el texto queda más lejos de él que en los títulos a media página.
headings.columnHeadSpace: 'remainder'deja esa fracción de línea sobre el título (encabezados). Conviene a un libro a una columna, donde ninguna columna vecina delata que el título empieza un poco más abajo.
Créditos
- Receta
- Ignacio Ferro
- Texto
- Texto original, CC BY 4.0
- Fuentes
- IBM Plex Serif (SIL OFL 1.1) · IBM Plex Sans Condensed (SIL OFL 1.1) · IBM Plex Mono (SIL OFL 1.1)
- Código
- MIT, como Postext
Editar este texto ↗ (se abre en una nueva pestaña)Carpeta de la receta en GitHub ↗ (se abre en una nueva pestaña)


