Saltar al contingut principal
Recepta número 7

Receptari · Capítol 5 · Estructura del llibre

Un llibre fet de capítols solts

buildBundle compon cinc fitxers Markdown com un sol llibre: cada capítol obre en pàgina senar i pàgines, capítols i figures es numeren correlativament.

En aquesta pàgina
Sortida
Canvas · PDF
Nivell
Avançat
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.25.0 · postext-pdf ≥ 1.25.0
Llicència
Actualitzada el 10 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Mostra en castellà: encara no hi ha edició en català
  • Format 150 × 200 mm
  • 1 columna
  • Andada Pro 10,4/14,2
  • Figtree
  • Rozha One
  • 11 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 85 ms
  • 229 línies de codi

En poques paraules

Un petit manual d'apicultura escrit en fitxers separats, un per capítol. Postext els uneix en un sol llibre i els números de pàgina, capítol i figura continuen d'un fitxer al següent.

Què compondràs

Un any d'abellar és un manual breu de quatre capítols, un per estació. Arrenca a la tardor, quan surt l'última alça i comença l'any de l'apicultor. Cada capítol és un fitxer Markdown sense números de pàgina, capítol ni figura. buildBundle porta el compte d'un fitxer a l'altre i compon els capítols, més un cinquè fitxer amb la coberta i l'índex, com un llibre d'onze pàgines. Cada capítol obre en pàgina senar, sota una cantonada de bresca que porta el seu número. L'índex, a la pàgina parella davant de Tardor, repeteix aquesta obertura en mirall, amb el títol enganxat al llom, i dona la pàgina de cada capítol. El mateix quadre de cria, dibuixat amb codi, surt a cada capítol, de la figura 1.1 a la 4.1. La pàgina 6 queda en blanc perquè Hivern cap en una pàgina i Primavera ha d'obrir en senar.

Aquesta recepta respon a

  • Com compono un llibre de diversos capítols perquè la numeració de pàgines, figures i capítols continuï de l'un a l'altre?
  • Com afegeixo un índex que s'actualitzi sol (línies de punts, números de pàgina, autors, files de part)?
  • Com forço un salt de pàgina o de columna, i faig que cada capítol comenci en pàgina senar?
  • Com amago les capçaleres a les obertures i a les pàgines en blanc, o pinto una pàgina parella en blanc amb el color de la part?

La resposta curta

script.js · línies 71–102al codi complet
// buildBundle lays the documents out in order with one config and carries state from each to
// the next: the pages already set (so parity goes on), the folio, the chapter and figure counts.
const book = () => buildBundle({ chapters, config: config(), resources });
const config = () => ({
  headings: { ...display, levels: [
    // Every chapter opens on a recto: after a chapter that ends on one, the next document
    // starts with a blank verso of its own.
    { level: 1, breakBefore: { enabled: true, parity: 'odd' },
      // '{1}' puts the number in the PDF bookmarks ('1 Autumn'); the contents and
      // {chapterNumber} count the chapters in order either way.
      numberingTemplate: '{1}', advancedDesign: opener,
      span: 'page' }, // in the column a design stops at the column's foot: the cover would too
    subhead,
  ] },
  // The cover and the contents are headings that take no number, no contents entry and no
  // running heads, so Autumn is still chapter 1. Both inherit span 'page', which starts
  // each on a page of its own, and parity 'odd', which the contents turn off: it would
  // leave page 2 blank (gotcha: style-inherits-break).
  headingStyles: [
    { id: 'cover', numbered: false, toc: false, advancedDesign: cover, ...bare },
    { id: 'contents', numbered: false, toc: false, breakBefore: { enabled: false },
      advancedDesign: contentsOpener, ...bare },
  ],
  // :::toc in the first document lists the whole book with the folio each chapter lands on:
  // buildBundle lays the book out again (three passes at most) until those folios settle.
  toc: contents,
  // The locale picks the hyphenation patterns and names the figures Figure or Figura. They
  // number {h1}.{n}, and the counters carry on from document to document (Winter's is 2.1).
  locale: t({ en: 'en-us', es: 'es' }),
  colorPalette, page, layout: { layoutType: 'single' }, bodyText, captionStyle, calloutStyles,
  header, footer, // the look: above, and in the regions below
});

Ingredients

Tipografia
Andada Pro, Rozha One, Figtree (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Un fitxer per capítol

script.js · línies 337–338al codi complet
// Nothing in a chapter says where it lands: buildBundle works that out from the order.
const chapters = [front, autumn, winter, spring, summer].map((markdown) => ({ markdown }));

Cada estació és un document propi, així que pots reescriure un capítol sense obrir els altres. El primer document porta el frontmatter, la coberta i l'índex. Les seves metadades són les del llibre: {title} i {author} les imprimeixen a tots els capítols, i el PDF en pren el títol i l'autora.

#2 · Regles que passen d'un document a l'altre

El codi d'aquest pas és la resposta curta de més amunt. buildBundle compon els documents en ordre amb una sola configuració i passa a cadascun una continuation amb el que han deixat els anteriors: el nombre de pàgines físiques ja compostes, perquè segueixin la paritat, els marges en mirall i les capçaleres de parelles i senars; el foli següent, i els comptadors de capítols i figures. Amb parity: 'odd', un capítol que segueix un altre acabat en pàgina senar comença amb una pàgina parella en blanc, i aquesta pàgina pertany al seu propi document (salt de pàgina previ). La coberta i l'índex són estils d'encapçalament amb numbered: false, per la qual cosa Tardor continua sent el capítol 1. Tots dos hereten del nivell de capítol span: 'page', que posa cadascun a la seva pàgina sense necessitat de :::pagebreak. L'estil de l'índex desactiva la paritat heretada, que deixaria en blanc la pàgina 2.

#3 · Un índex de tot el llibre

script.js · línies 215–228al codi complet
const contents = {
  levels: [
    { level: 1, fontFamily: 'Rozha One', fontSize: pt(16), lineHeight: pt(18),
      numberFontFamily: 'Figtree', numberFontSize: pt(11), numberFontWeight: 700,
      numberColor: col('accent'), numberWidth: mm(7), numberGap: mm(4), marginTop: pt(8) },
    // Sections: 9.3 pt in the muted colour, indented 11 mm (number 7 + gap 4) to the titles.
    { level: 2, fontSize: pt(9.3), lineHeight: pt(13.5), indent: mm(11), color: col('muted') },
  ],
  pageNumber: { fontFamily: 'Figtree', fontSize: pt(8.5), fontWeight: 600, width: mm(7) },
  leader: { char: '. ', gap: mm(2) },
  // A second line under each chapter, from its {months="…"} heading attribute.
  subtitle: { enabled: true, attr: 'months', fontFamily: 'Andada Pro', fontSize: pt(9),
    color: col('muted') }, // italic by default
};

:::toc és al primer document, però recull els capítols i les seccions de tot el llibre. buildBundle compon el llibre, anota cada títol amb la pàgina que li ha tocat i el torna a compondre amb aquest esquema fins que els folis deixen de moure's, tres passades com a màxim (índex general). Els mesos sota cada títol surten d'un atribut del títol, {months="…"}, que també imprimeix l'obertura.

#4 · Una obertura, en mirall per a l'índex

script.js · línies 184–211al codi complet
const corner = (id, edge) => ({ kind: 'image', id, resourceId: id,
  placement: { anchor: { to: 'bleed', edge }, size: { width: mm(CORNER.width) } } });
const months = { kind: 'text', id: 'months', content: '{attr.months}', ...label,
  color: col('accent'), placement: at('top-left', 0, 14, 'container') };
const title = { kind: 'text', id: 'title', content: '{titleText}', ...display, fontSize: pt(42),
  lineHeight: 1.05, align: 'left', overflow: 'wrap', placement: below('months', 1.5, 100) };
const opener = { enabled: true, minHeight: mm(52), slot: { elements: [
  corner('cells', 'top-right'),
  // The number's box is centred on its cell. Comb and number both hang from the bleed's top
  // right, so a bleed (page.cutLines) moves them together.
  { kind: 'text', id: 'number', content: '{chapterNumber}', ...display, fontSize: pt(40),
    lineHeight: 1, align: 'center', placement: { size: { width: mm(NUMBER.box) },
      ...at('top-right', NUMBER_CELL.x + NUMBER.box / 2 - CORNER.width,
        NUMBER_CELL.y - NUMBER.rise, 'bleed') } },
  months, title,
  { kind: 'text', id: 'lead', content: '{attr.lead}', fontFamily: 'Andada Pro', italic: true,
    fontSize: pt(11.5), lineHeight: 1.35, color: col('ink'), align: 'left', overflow: 'wrap',
    placement: below('title', 3, 88) },
] } };
// The contents mirror it on the verso: the comb in the outer corner, the book's subtitle and
// the title set flush right against the spine, on the same lines as Autumn's across the spread.
const flushRight = (element, placement) => ({ ...element, align: 'right',
  placement: { ...placement, size: { width: 'fill' } } });
const contentsOpener = { ...opener, minHeight: mm(40), slot: { elements: [
  corner('comb', 'top-left'),
  flushRight({ ...months, content: '{subtitle}' }, months.placement),
  flushRight(title, below('months', 1.5)),
] } };

{chapterNumber} continua comptant des dels documents compostos abans, així que l'obertura de Primavera mostra un 3 encara que el seu fitxer no porta cap número. La caixa del número es calcula a partir del centre de la seva cel·la de la bresca, i número i bresca pengen tots dos de la cantonada superior dreta de la sang; si canvies el format o afegeixes sang per a impremta, es mouen junts. A l'índex, l'avanttítol (que surt de {subtitle}) i el títol van alineats a la dreta, contra el llom, i la bresca passa a la cantonada exterior de la pàgina parella; així el seu títol cau a la mateixa altura que el de Tardor a la doble pàgina.

#5 · Capçaleres a tots els documents

script.js · línies 232–248al codi complet
const head = (id, content, parity, placement, extra = {}) => ({
  kind: 'text', id, content, parity, pages: 'body', // never on openers or blank pages
  ...label, color: col('muted'), placement, ...extra,
});
const folio = { fontSize: pt(8.5), fontWeight: 700, color: col('accent') };
// Only the first document has frontmatter, and its {title} is the book's in every chapter.
const header = { elements: [
  head('verso-folio', '{pageNumber}', 'even', at('top-left', MARGIN.outer, HEAD.y), folio),
  head('verso-title', '{title}', 'even', at('top-left', MARGIN.outer + HEAD.gap, HEAD.y)),
  // {chapterTitle} and {pageNumber} are worked out page by page, in every document.
  head('recto-title', '{chapterTitle}', 'odd',
    at('top-right', -(MARGIN.outer + HEAD.gap), HEAD.y)),
  head('recto-folio', '{pageNumber}', 'odd', at('top-right', -MARGIN.outer, HEAD.y), folio),
] };
// Openers carry a drop folio instead, 8 mm under the text block.
const footer = { elements: [head('drop-folio', '{pageNumber}', 'all',
  at('top', 0, 8, 'container'), { pages: 'opener', fontWeight: 700 })] };

Només el primer document té frontmatter, i buildBundle el passa a tots els capítols, així que la capçalera de les pàgines parelles imprimeix el {title} del llibre als cinc documents. {chapterTitle} i {pageNumber} es resolen pàgina a pàgina i surten a tots els documents; la pàgina 11, l'única senar de text corregut, porta ESTIU al costat del foli. pages: 'body' deixa sense capçalera les obertures i la pàgina en blanc.

#6 · Plecs en pantalla, un PDF per al llibre

script.js · línies 369–379al codi complet
const text = chapters.map((chapter) => chapter.markdown).join('\n');
await prepareFonts(text, config(), kitFonts(FONTS));
const art = { cover: coverArt(), cells: cornerArt(true), comb: cornerArt(false) };
for (const [season, plan] of Object.entries(SEASONS)) art[`${season}-frame`] = frameArt(plan);
for (const [id, markup] of Object.entries(art)) await loadSvg(`${id}.svg`, markup);
// One VDTDocument per Markdown document.
const docs = await withLoadedFonts(book, { ...kitFonts(FONTS), text });
showPages(docs, { title: t({ en: 'A Beekeeper’s Year', es: 'Un año de colmenar' }) });
// renderToPdf takes the array: one file for the book, with a bookmark per chapter.
offerPdf(() => renderToPdf(docs, { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),
  `${RECIPE}.pdf`);

buildBundle retorna una llista de documents, un per fitxer Markdown. showPages aparella les pàgines per pageIndexOffset + page.index, així que la pàgina 1 queda sola, com a senar, i les altres queden acarades per parells: la 2 amb la 3, la 4 amb la 5, i així fins al final. renderToPdf rep la mateixa llista i escriu un únic fitxer amb els folis del llibre i un marcador per cada capítol i secció.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 007 · One book from separate chapters ══════════════════════════
// https://postext.dev/en/cookbook/book-from-chapters
// Code: MIT · Text: original (CC BY 4.0) · Drawings: generated in code (CC BY 4.0)
// Fonts: Andada Pro, Rozha One, Figtree (SIL OFL 1.1) · Needs postext ≥ 1.25.0
// A handbook in four seasons written as five Markdown documents, laid out by buildBundle as
// one book: parity, folios, chapter and figure numbers and the contents run straight through.
import {
  buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
} 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 = 'book-from-chapters';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
const palette = { // every colour in the config links to one of these, so the book can be retinted
  ink: '#2a2218', // text and display type
  honey: '#d99a1e', // the drawings only: the cover and the comb cells
  accent: '#7a4e12', // the text accent (7:1 on paper): numbers, labels, subheads; main-color too
  pollen: '#c4692b', comb: '#f7e7c4', rule: '#d8c8a8', // figures: pollen, wax, wood and walls
  muted: '#6e634f', paper: '#fffdf7', // running heads, colophon, contents sections; the page
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  // The engine's defaults link to 'main-color': point it at the accent, so nothing prints blue.
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// The geometry, in mm. The drawings, the opener and the running heads are derived from it.
const TRIM = { width: 150, height: 200 }; // a small handbook
const MARGIN = { top: 22, bottom: 22, inner: 19, outer: 15 }; // mirrored
const MEASURE = TRIM.width - MARGIN.inner - MARGIN.outer; // the text width: 116 mm
const SQRT3 = Math.sqrt(3); // comb cells of radius r sit √3·r apart, their rows 1.5·r apart
const CORNER = { width: 84, height: 70, r: 9.5 }; // the openers' comb, and its cell radius
const NUMBER_CELL = { x: 4 * SQRT3 * CORNER.r, y: 2 * 1.5 * CORNER.r }; // row 2, cell 4
// The chapter number's box: 20 mm wide, its top 8 mm above the cell's centre, which is where
// a 40 pt Rozha One figure sits optically centred in the cell.
const NUMBER = { box: 20, rise: 8 };
const FRAME = { width: MEASURE, height: 50 }; // the brood frame figures, at the text width
const HEAD = { y: 12, gap: 8 }; // running heads 12 mm from the top edge, 8 mm folio to text
const LEAD = 14.2; // body leading in pt: the baseline grid
// The look: a small handbook, mirrored, justified Andada Pro on the grid; Rozha One titles.
const page = { // mirror: left is the inner margin, right the outer
  sizePreset: 'custom', width: mm(TRIM.width), height: mm(TRIM.height), dpi: 150,
  backgroundColor: col('paper'), margins: { top: mm(MARGIN.top), bottom: mm(MARGIN.bottom),
    left: mm(MARGIN.inner), right: mm(MARGIN.outer), mirror: true },
};
const bodyText = { // justified, hyphenated, optimal line breaks and widow control: by default

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

#Imprimeix un capítol amb els folis del llibre

Passa un sol document a renderToPdf per treure una prova de Primavera, numerada del 6 al 8 com al llibre. La pàgina 6 en blanc va amb ella, perquè la pàgina parella en blanc que precedeix una obertura pertany al capítol que obre després.

-offerPdf(() => renderToPdf(docs, { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),
+offerPdf(() => renderToPdf(docs[3], { fontProvider: fontsourceProvider, resourceBytes: imageBytes }),

#Numera les figures correlativament en tot el llibre

Un comptador de figures que no es reinicia numera els quatre quadres de l'1 al 4 en tot el llibre, en lloc d'1.1 a 4.1.

   buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas, registerResourceImage,
+  defaultResourceTypes,
@@
   locale: t({ en: 'en-us', es: 'es' }),
+  resourceTypes: defaultResourceTypes(LANG)
+    .map((type) => ({ ...type, numberingTemplate: '{n}', resetOn: 'never' })),

Errors freqüents

Error freqüent

Un estil de títol hereta el salt de pàgina del seu nivell

Una entrada de headingStyles pren del seu nivell de títol tot allò que no fixa, també breakBefore. Un índex o un colofó amb estil sobre un H1 després d'un :::pagebreak hereta la paritat 'odd' i cau darrere d'una pàgina en blanc. Dona a aquest estil breakBefore: { enabled: false }. Estils de títol →

Error freqüent

La pàgina 1 és senar: planifica amb números físics

La pàgina 1 queda a la dreta i la 2 és la primera pàgina parella, així que planifica els plecs amb números de pàgina físics: una obertura en pàgina parella queda davant de la senar que la segueix. Salts de pàgina i de columna →

Comprovació del Sandbox · chapterFrontmatterIgnored

Frontmatter del capítol ignorat

Per què. Només compta el frontmatter del primer capítol; un capítol posterior comença amb un bloc de frontmatter que es descarta.

Solució. Deixa les metadades del llibre al primer capítol i fes servir atributs d'encapçalament per als valors de cada capítol. Documentació →

  • A dalt d'una pàgina, i sota una figura que l'encapçala, un títol de secció perd el seu marginTop. Si l'aire del títol surt del marge, en aquests dos llocs queda a una línia del seu text i a la resta, a una línia i mitja. Aquí l'aire és a la mateixa línia del títol: lineHeight fa una línia i mitja i el marge, una línia, així que tots els títols de secció del llibre queden a la mateixa distància del seu text.
  • Per defecte, una línia justificada pot estirar els espais fins al doble de la seva amplada, i l'algorisme de tall ho prefereix a un guionet. Composta així, l'edició anglesa no partia ni una paraula i deixava espais gairebé del doble al costat de línies atapeïdes al 0,7. maxWordSpacing: 1.7 obliga l'algorisme a partir paraules. Després de canviar-ho, revisa l'última línia de cada paràgraf: un límit més estricte hi pot deixar una paraula sola, i s'arregla canviant unes quantes paraules del paràgraf.

Crèdits

Text
Text original, CC BY 4.0
Fonts
Andada Pro (SIL OFL 1.1) · Rozha One (SIL OFL 1.1) · Figtree (SIL OFL 1.1)
SandboxPDF