Saltar al contingut principal
Recepta número 115

Receptari · Capítol 10 · Sortida i integració

Un llibre, dos EPUB 3: maquetació fixa i fluida

renderToEpub, de postext-epub, escriu els capítols de buildBundle com un EPUB de maquetació fixa i un altre de fluid; readEpub mostra què porta cadascun.

En aquesta pàgina
Sortida
Canvas · EPUB
Nivell
Avançat
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.65.0
Llicència
Actualitzada el 31 d’oct. del 2026
Codi MIT · Text MIT
  • Mostra en castellà: encara no hi ha edició en català
  • Format 120 × 190 mm
  • 1 columna
  • Libre Caslon Text 9,6/13,5
  • Jost
  • Libre Caslon Display
  • 17 pàgines
  • Nivell
  • Postext 1.65.0
  • Compost en 196 ms
  • 178 línies de codi

En poques paraules

Un conte curt compost una vegada per imprimir i desat com dos llibres electrònics: un que conserva cada pàgina impresa i un altre amb el text que el mòbil o el lector electrònic recompon a la seva mida.

Què compondràs

¡Adiós, Cordera!, el conte de Clarín, en tres capítols sobre una pàgina de 120 × 190 mm, amb portada, pàgina de crèdits al dors i una obertura enfonsada a cada capítol; l'edició anglesa compon divuit faules d'Isop amb el mateix disseny. El llibre es compon una vegada, capítol a capítol, i aquesta composició dona dos fitxers EPUB 3. El de maquetació fixa conserva cada pàgina impresa: les obertures, les capçaleres i els talls de línia, en la Caslon incrustada. El fluid conserva el text i la seva estructura, i el sistema de lectura el torna a compondre en un mòbil o en una pantalla de tinta electrònica. Tots dos es baixen des de la pàgina i tots dos passen EPUBCheck, el validador del W3C.

Aquesta recepta respon a

  • Com exporto el meu llibre a EPUB, amb pàgines fixes o amb text fluid?

La resposta curta

script.js · línies 302–316al codi complet
const { title, subtitle, author } = docs[0].metadata; // the first chapter's front matter
const book = {
  metadata: { title, subtitle, creators: [author], language: LANG,
    rights: t({ en: 'Public domain', es: 'Dominio público' }),
    // A fixed date gives the same bytes on every run; the identifier (a urn:uuid) comes
    // from the title, the author and the language, so a new version keeps its place.
    modified: new Date('2026-10-04T00:00:00Z') },
  // Every face the pages use, as bytes: a face left out is set in the reader's own
  // (gotcha: epub-embeds-given-fonts).
  fonts: await epubFonts(FONTS),
  onWarning: (w) => console.warn(`[epub] ${w.kind}`, w.family ?? w.fileId ?? w.detail),
};
// The same documents renderToPdf would print: one per chapter, in book order.
const fixed = await renderToEpub(docs, { ...book, layout: 'fixed' });
const reflowable = await renderToEpub(docs, { ...book, layout: 'reflowable' });

Ingredients

Tipografia
Libre Caslon Text, Libre Caslon Display, Jost (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · Compon el llibre per capítols

script.js · línies 42–61al codi complet
// Each line spans the measure and centres its text; the rule centres under the title.
const text = (id, content, fontFamily, size, placement, extra = {}) => ({ kind: 'text', id,
  content, fontFamily, fontSize: pt(size), color: col('ink'), align: 'center',
  overflow: 'wrap', lineHeight: 1.15, ...extra,
  placement: { ...placement, size: { width: 'fill', height: 'auto' } } });
const rule = (id, below, y) => ({ kind: 'rule', id, direction: 'horizontal', thickness: pt(0.75),
  color: col('accent'),
  placement: { ...at(below, 'below', (MEASURE - 10) / 2, y), size: { width: mm(10) } } });
const titlePage = { id: 'title-page', header: { elements: [] }, footer: { elements: [] },
  marginBottom: pt(0), advancedDesign: { enabled: true, minHeight: mm(120), slot: { elements: [
    text('author', '{author}', LABEL, 9, at('container', 'top-left', 0, 30), caps(9)),
    text('title', '{titleText}', DISPLAY, 34, at('#author', 'below', 0, 8)),
    rule('rule', '#title', 6),
    text('subtitle', '{subtitle}', TEXT, 11, at('#title', 'below', 0, 13), { italic: true }),
  ] } } };
const opener = { enabled: true, minHeight: mm(56), slot: { elements: [
  text('kicker', '{attr.kicker}', LABEL, 8, at('container', 'top-left', 0, 14), caps(8)),
  text('title', '{titleText}', DISPLAY, 28, at('#kicker', 'below', 0, 4)),
  rule('rule', '#title', 5),
] } };

buildBundle compon cada capítol com un document propi i passa d'un a l'altre el número de pàgina i la paritat, així que docs és la mateixa llista que imprimiria renderToPdf. L'escriptor d'EPUB llegeix aquesta llista: cada capítol és una entrada de l'índex de navegació, i el fitxer fluid escriu un document XHTML per capítol. La portada i la seva pàgina de crèdits formen el primer capítol, i el seu frontmatter dona el títol, el subtítol i l'autor del llibre.

#2 · Dona a l'escriptor els fitxers de les fonts

script.js · línies 281–292al codi complet
// Only the latin files: they hold every letter of both samples. A text beyond Latin-1 would
// add each family's latin-ext file with its unicodeRange.
const epubFonts = (faces) => Promise.all(Object.entries(faces).flatMap(([family, specs]) =>
  specs.map(async (spec) => {
    const [weight, style] = [parseInt(spec, 10), spec.endsWith('i') ? 'italic' : 'normal'];
    const id = fontsourceId(family);
    const res = await fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/`
      + `${id}-latin-${weight}-${style}.woff2`);
    if (!res.ok) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
    const bytes = new Uint8Array(await res.arrayBuffer());
    return { family, weight, style, format: 'woff2', bytes };
  })));

Les fonts que ha carregat el navegador no són fitxers que l'escriptor pugui llegir, així que el codi torna a demanar els mateixos woff2 de Fontsource, que el navegador ja té a la memòria cau. Cadascun entra a l'EPUB com un fitxer amb la seva regla @font-face. Sense ells, la maquetació fixa col·locaria el text compost en Caslon amb una font del lector, i les línies ja no cabrien a la seva mida.

#3 · Escriu les dues versions

El codi és la resposta curta de dalt. layout: 'fixed' escriu un document XHTML per pàgina impresa, a la mida de la pàgina refilada i amb text de debò, que es pot seleccionar; layout: 'reflowable' refà els paràgrafs a partir de les línies compostes, treu els guions que hi van afegir els talls de línia i treu un full d'estils de la configuració. Una data modified fixa fa que cada execució doni els mateixos bytes. Les metadades surten del frontmatter del primer capítol, de manera que el títol i l'autor del fitxer són els que s'imprimeixen a la portada.

#4 · Llegeix cada fitxer de tornada

script.js · línies 320–342al codi complet
const el = (tag, css, text) => Object.assign(document.createElement(tag),
  { textContent: text ?? '' }, { style: css });
const shelf = el('section', 'display: flex; flex-wrap: wrap; gap: 16px; justify-content: center;'
  + 'padding: 24px 16px 0; color: #d9d5cc; font: 13px/1.5 system-ui, sans-serif');
shelf.id = 'epub';
for (const [layout, bytes] of [['fixed', fixed], ['reflowable', reflowable]]) {
  const epub = readEpub(bytes); // what a reading system opens: spine, contents, page list
  const file = `${RECIPE}-${layout}.epub`;
  const card = el('article', 'width: min(420px, 92vw); padding: 16px 18px;'
    + 'border: 1px solid #2c3038; border-radius: 6px; background: #15181d');
  const spine = el('ol', 'margin: 8px 0; padding-left: 22px; max-height: 9em; overflow: auto');
  spine.append(...epub.spine.map((item) => el('li', '', item.path.slice(epub.root.length))));
  const link = el('a', 'color: #d8a21a', `Download ${file}`);
  link.href = URL.createObjectURL(new Blob([bytes], { type: 'application/epub+zip' }));
  link.download = file;
  card.append(el('h2', 'margin: 0; font-size: 15px; color: #f4f1ea', `EPUB 3 · ${epub.layout}`),
    el('p', 'margin: 4px 0 0', `${epub.spine.length} documents in the spine · `
      + `${epub.toc.length} contents entries · ${epub.pageList.length} print pages · `
      + `${Math.round(bytes.length / 1024)} KB`), spine, link);
  shelf.append(card);
}
document.getElementById('pages').before(shelf);
kitStatus(`${docs.length} documents laid out · two EPUB 3 files`);

readEpub obre el fitxer com l'obre un sistema de lectura: l'ordre de lectura (spine), l'índex, la llista de pàgines i la maquetació. El fitxer fix té una entrada per pàgina; el fluid, quatre, una per capítol. Tots dos porten la llista dels folis impresos, així que una cita de la pàgina 9 es troba en qualsevol dels dos. L'enllaç <a download> dona nom als bytes; res no passa per un servidor.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 115 · One book, two EPUB 3 files: fixed and reflowable ════
// https://postext.dev/en/cookbook/epub-fixed-and-reflowable
// Code: MIT · Text: Aesop, tr. G. F. Townsend, 1867; L. Alas, Clarín, 1893 (PD) · Pictures: none
// Fonts: Libre Caslon Text, Libre Caslon Display, Jost (SIL OFL 1.1) · Needs postext ≥ 1.65.0
//
// A small book of three chapters, laid out once with buildBundle and written as two EPUB 3
// files with postext-epub: a fixed layout that keeps every printed page, and reflowable text
// that a phone or an e-reader sets again. Each file is read back with readEpub to list what
// a reading system will open, with a link to download it.
import {
  buildBundle, prepareFonts, withLoadedFonts, renderPageToCanvas,
} from 'https://esm.sh/postext';
import { renderToEpub, readEpub } from 'https://esm.sh/postext-epub';

const LANG = 'es'; // @lang: the language of the sample document ('en' | 'es')
const RECIPE = 'epub-fixed-and-reflowable';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: semantic colours, every one linked by id
const palette = {
  ink: '#211e1b', // text: a warm near-black
  accent: '#2d5872', // Prussian blue: kickers, rules, folios
  rule: '#c8c0b4', // the title page's hairline
  muted: '#6b645d', // running heads and the imprint
  paper: '#fbf8f1', // an off-white page, kept in the fixed-layout EPUB
};
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' } })),
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion
const [TEXT, DISPLAY, LABEL] = ['Libre Caslon Text', 'Libre Caslon Display', 'Jost'];
const [TRIM_W, TRIM_H, TOP, BOTTOM, INNER, OUTER] = [120, 190, 20, 22, 16, 15]; // mm
const MEASURE = TRIM_W - INNER - OUTER; // 89 mm: about 62 characters of Libre Caslon Text
const LEAD = 13.5; // pt: the body leading
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const caps = (size, color = 'accent') => ({ fontFamily: LABEL, fontSize: pt(size),
  fontWeight: 600, letterSpacing: pt(size * 0.2), textTransform: 'uppercase', color: col(color) });

// #region openers: a title page, then each chapter sunk under its kicker and a short rule
// Each line spans the measure and centres its text; the rule centres under the title.
const text = (id, content, fontFamily, size, placement, extra = {}) => ({ kind: 'text', id,
  content, fontFamily, fontSize: pt(size), color: col('ink'), align: 'center',
  overflow: 'wrap', lineHeight: 1.15, ...extra,
  placement: { ...placement, size: { width: 'fill', height: 'auto' } } });
const rule = (id, below, y) => ({ kind: 'rule', id, direction: 'horizontal', thickness: pt(0.75),
  color: col('accent'),

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

#Posa una imatge de coberta a la maquetació fixa

Pinta la portada en un canvas i passa-la com a coberta; showsFirstPage diu a l'escriptor que no l'afegeixi com una pàgina més.

+const canvas = document.createElement('canvas');
+renderPageToCanvas(docs[0].pages[0], docs[0], canvas, { scale: 2 });
+const png = await new Promise((done) => canvas.toBlob(done, 'image/png'));
+const cover = { bytes: new Uint8Array(await png.arrayBuffer()), mediaType: 'image/png',
+  showsFirstPage: true };
-const fixed = await renderToEpub(docs, { ...book, layout: 'fixed' });
+const fixed = await renderToEpub(docs, { ...book, layout: 'fixed', cover });

#Imprimeix els mateixos capítols en PDF

renderToPdf(docs, …), de postext-pdf, rep la mateixa llista, així que el PDF, l'EPUB i la pantalla surten d'una sola composició. La novel·la catalana de butxaca mostra el costat del PDF.

Errors freqüents

Error freqüent

renderToEpub només incrusta les fonts que li passes

Les fonts que ha carregat el navegador no són fitxers que postext-epub pugui llegir: passa a options.fonts els bytes de cada font que fan servir les pàgines (els mateixos woff2 de Fontsource que va carregar la pàgina). Una font que falti s'avisa com a missingFont, i el sistema de lectura compon aquest text amb una de seva, que en una maquetació fixa ja no cap a les línies amb què es va compondre la pàgina. Incrusta només fonts la llicència de les quals ho permeti. Exportació a EPUB →

El fitxer fluid conserva el text d'un títol, però no el seu disseny: l'avanttítol de cada obertura és un element de disseny i no forma part del text. El que el lector hagi de veure va al mateix títol o al text.

Crèdits

Text
  • Eighteen fables from Three Hundred Æsop’s Fables, translated from the Greek by George Fyler Townsend (London, 1867), the opening capitals of each fable set in lower case · Aesop, tr. George Fyler Townsend · domini públic
  • ¡Adiós, Cordera!, complete, from El Señor y lo demás, son cuentos (Madrid, 1893), its five parts grouped in three chapters, with dialogue dashes and « » quotation marks · Leopoldo Alas, Clarín · domini públic
Fonts
Libre Caslon Text (SIL OFL 1.1) · Libre Caslon Display (SIL OFL 1.1) · Jost (SIL OFL 1.1)
Sandbox