Pular para o conteúdo principal
Receita número 7

Receitas · Capítulo 5 · Estrutura do livro

Um livro feito de capítulos separados

buildBundle junta cinco arquivos Markdown num livro: cada capítulo abre em página ímpar, e páginas, capítulos e figuras seguem numerados de arquivo em arquivo.

Nesta página
Saída
Canvas · PDF
Nível
Avançado
Postext
Testada com o Postext 1.65.0
Requer ≥ 1.25.0 · postext-pdf ≥ 1.25.0
Licença
Atualizada em 10 de out. de 2026
Código MIT · Texto CC BY 4.0

p. 4–5 de 11

  • Amostra em inglês: ainda sem edição em português
  • Refile 150 × 200 mm
  • 1 coluna
  • Andada Pro 10,4/14,2
  • Figtree
  • Rozha One
  • 11 páginas
  • Nível
  • Postext 1.57.1
  • Diagramado em 95 ms
  • 229 linhas de código

Em poucas palavras

Um pequeno manual de apicultura escrito em arquivos separados, um por capítulo. O Postext junta tudo num livro só, e os números de página, capítulo e figura continuam de um arquivo para o outro.

O que você vai compor

A Beekeeper’s Year é um manual pequeno em quatro capítulos, um por estação. Ele começa pelo outono (Autumn), porque o ano do apicultor começa quando sai o último mel. Cada capítulo é um arquivo Markdown separado, sem nenhum número de página, capítulo ou figura. buildBundle leva essas contagens de um arquivo para o seguinte e compõe os capítulos, com um quinto arquivo para a capa e o sumário, como um livro de onze páginas. Todo capítulo abre numa página ímpar, sob um canto de favo que traz o número dele. O sumário, na página par diante de Autumn, espelha essa abertura com o título encostado na lombada e dá o fólio de cada capítulo. Um quadro de cria, desenhado em código, aparece uma vez em cada capítulo, das Figuras 1.1 a 4.1. A página 6 fica em branco porque Winter cabe numa página e Spring precisa abrir numa ímpar.

Esta receita responde a

  • Como faço para compor um livro de vários capítulos de modo que a numeração de páginas, figuras e capítulos continue de um para o outro?
  • Como acrescento um sumário que se atualiza sozinho (pontilhados, números de página, autores, linhas de parte)?
  • Como forço uma quebra de página ou de coluna e faço cada capítulo começar em página ímpar?
  • Como oculto os cabeços nas aberturas e nas páginas em branco, ou pinto uma página par em branco com a cor da parte?

A resposta curta

script.js · linhas 71–102no código completo
// 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
});

Ingredientes

Tipografia
Andada Pro, Rozha One, Figtree (SIL OFL 1.1)
Materiais
Nenhum: todas as imagens são desenhadas em código

Preparo

#1 · Um arquivo por capítulo

script.js · linhas 337–338no código completo
// 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 estação é um documento próprio, por isso você pode reescrever um capítulo sem abrir os outros. O primeiro documento tem o front matter, a capa e o sumário. Os metadados dele são os do livro: {title} e {author} os imprimem em todos os capítulos, e o PDF tira dele o título e a autoria.

#2 · Regras que passam de um documento para outro

O código deste passo está na resposta curta, mais acima. buildBundle diagrama os documentos em ordem com uma só configuração e passa a cada um uma continuation com o que veio antes: o número de páginas físicas já compostas, para que a paridade, as margens espelhadas e os cabeços de páginas pares e ímpares continuem; o fólio seguinte; e os contadores de capítulos e figuras. Com parity: 'odd', um capítulo que vem depois de outro terminado numa página ímpar começa com uma página par em branco, e essa página pertence ao próprio documento dele (quebra antes). A capa e o sumário são estilos de título com numbered: false, e por isso Autumn continua sendo o capítulo 1. Os dois herdam span: 'page' do nível de capítulo, o que põe cada um numa página só dele sem :::pagebreak. O estilo do sumário desativa a paridade herdada, que de outro modo deixaria a página 2 em branco.

#3 · Sumário do livro inteiro

script.js · linhas 215–228no código completo
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 fica no primeiro documento, mas lista os capítulos e as seções do livro inteiro. buildBundle diagrama o livro, recolhe cada título com o rótulo de página que ele recebeu e diagrama o livro de novo com esse esquema até os rótulos pararem de mudar, no máximo três passadas (sumário). Os meses sob cada título vêm de um atributo do título, {months="…"}, que a abertura também imprime.

#4 · Uma abertura, espelhada no sumário

script.js · linhas 184–211no código completo
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 contando a partir dos documentos diagramados antes, e assim a abertura de Spring imprime 3, embora o arquivo dela não tenha número nenhum. A caixa do número é calculada a partir do centro da célula do favo, e número e favo pendem os dois do canto superior direito da sangria; mudar o formato ou acrescentar sangria para a gráfica os move juntos. Na página do sumário, o chapéu, lido de {subtitle}, e o título ficam alinhados à direita, encostados na lombada, e o favo passa para o canto externo da página par. O título fica então na mesma altura que o de Autumn na página em frente.

#5 · Cabeços em todos os documentos

script.js · linhas 232–248no código completo
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 })] };

Só o primeiro documento tem front matter, e buildBundle o entrega a todos os capítulos, de modo que o cabeço das páginas pares imprime o {title} do livro nos cinco documentos. {chapterTitle} e {pageNumber} são resolvidos página a página e saem em todos os documentos; a página 11, a única ímpar de texto corrido, traz SUMMER ao lado do fólio. pages: 'body' tira os cabeços das aberturas e da página em branco.

#6 · Páginas duplas na tela, um PDF para o livro

script.js · linhas 369–379no código completo
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 devolve uma lista de documentos, um por arquivo Markdown. showPages emparelha as páginas por pageIndexOffset + page.index, por isso a página 1 fica sozinha como ímpar, e as páginas 2 e 3, 4 e 5 e assim por diante ficam frente a frente. renderToPdf recebe a mesma lista e grava um único arquivo com os rótulos de página do livro e um marcador para cada capítulo e seção.

A receita 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 = 'en'; // @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

O script.js montado funciona como está: cole-o como script de módulo em qualquer página ou abra a receita no CodePen. Pasta da receita no GitHub ↗ (abre em uma nova aba)

Variações

#Imprimir um capítulo com os fólios do livro

Passe um só documento para renderToPdf para tirar uma prova de Spring sozinho, numerado de 6 a 8 como no livro. A página 6 em branco vem junto, porque uma página par em branco antes de uma abertura pertence ao capítulo que abre depois dela.

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

#Numerar as figuras em sequência no livro todo

Um contador de figuras que nunca reinicia numera os quatro quadros de 1 a 4 através dos documentos, em vez de 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' })),

Erros comuns

Erro comum

Um estilo de título herda a quebra de página do seu nível

Uma entrada de headingStyles recebe do seu nível de título todos os campos que não define, inclusive breakBefore. Um sumário ou um colofão com estilo sobre um H1 depois de um :::pagebreak herda a paridade 'odd' e cai depois de uma página em branco. Dê a esse estilo breakBefore: { enabled: false }. Estilos de título →

Erro comum

A página 1 é ímpar: planeje com os números físicos

A página 1 fica à direita e a 2 é a primeira página par, então planeje as páginas duplas com os números físicos de página: uma abertura em página par fica de frente para a ímpar que vem depois dela. Quebras de página e de coluna →

Verificação do Sandbox · chapterFrontmatterIgnored

Front matter do capítulo ignorado

Por quê. Só o front matter do primeiro capítulo vale; um capítulo posterior começa com um bloco de front matter que é descartado.

Correção. Mantenha os metadados do livro no capítulo um e use atributos de título para os valores de cada capítulo. Docs →

  • No alto de uma página, e sob uma figura que encabeça a página, um intertítulo perde o marginTop. Um intertítulo que tira o espaço da margem fica a uma linha do texto nesses dois lugares e a uma linha e meia em todos os outros. Aqui o espaço está na própria linha do intertítulo: lineHeight é uma linha e meia e a margem, uma linha, de modo que todo intertítulo do livro fica à mesma distância do texto.
  • Por padrão, uma linha justificada pode esticar os espaços até o dobro da largura, e o algoritmo de quebra prefere isso a um hífen. Com esse padrão, a edição inglesa não tinha hífen nenhum, e linhas com espaços de quase o dobro da largura normal ficavam ao lado de linhas apertadas a 0,7. maxWordSpacing: 1.7 faz o algoritmo hifenizar. Depois de mudar esse valor, confira a última linha de cada parágrafo: um limite mais apertado pode deixar uma palavra sozinha ali, e trocar umas poucas palavras do parágrafo resolve.

Créditos

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