Saltar al contingut principal
Recepta número 148

Receptari · Capítol 11 · Còmic i manga

Un EPUB de còmic que es llegeix vinyeta a vinyeta

Un còmic breu exportat com a PDF, com a EPUB fix amb navegació per regions per llegir-lo vinyeta a vinyeta, com a EPUB per a Kindle i com a EPUB adaptable.

En aquesta pàgina
Gènere
Còmics
Sortida
Canvas · PDF · EPUB
Nivell
Intermedi
Postext
Provada amb Postext 1.65.0
Requereix ≥ 1.65.0 · postext-pdf ≥ 1.65.0
Llicència
Actualitzada el 31 d’oct. del 2026
Codi MIT · Text CC BY 4.0
  • Format 168 × 259 mm
  • 1 columna
  • Comic Neue 10,5/15
  • Bangers
  • 3 pàgines
  • Nivell
  • Postext 1.65.0
  • Compost en 299 ms
  • 184 línies de codi

En poques paraules

Un còmic de dues pàgines desat com a PDF d’impremta i com a llibres electrònics: un que conserva les pàgines i deixa anar de vinyeta en vinyeta, un altre per a Kindle i un altre amb els diàlegs com a text.

Què compondràs

El primer capítol de La llum de Porthcove: una portada i dues pàgines de còmic, maquetades una vegada i exportades de quatre maneres. El PDF és per a impremta. L’EPUB de maqueta fixa conserva les pàgines impreses i porta navegació per regions, així que un lector electrònic pot mostrar el llibre vinyeta a vinyeta, saltant de l’arribada al far a la ràdio i després a la Maya. Un segon EPUB fix hi afegeix Kindle Panel View; l’adaptable compon cada vinyeta com la seva imatge retallada seguida dels seus diàlegs. La pàgina llista cada fitxer tal com l’obrirà un lector, amb l’enllaç de baixada, en deu idiomes.

Aquesta recepta respon a

  • Com faig un EPUB de còmic que es llegeixi vinyeta a vinyeta?

La resposta curta

script.js · línies 264–279al codi complet
// The fixed layout keeps every printed page and writes regions.xhtml (EPUB Region-Based
// Navigation): one panel region per panel in reading order, its balloons nested in it.
// kindlePanelView adds Kindle's tap-to-magnify targets; the reflowable book sets each panel
// as its cropped picture followed by its lines as text.
const book = {
  metadata: { title: doc.metadata.title, creators: [doc.metadata.author], language: config().locale,
    modified: new Date('2026-10-07T00:00:00Z') }, // a fixed date: the same bytes on every run
  fonts: await epubFonts([LETTERING, SFX], markdown), // every face the pages set, as bytes
  resourceBytes: (fileId) => ({ bytes: imageBytes(fileId), mediaType: 'image/jpeg' }),
  onWarning: (w) => console.warn(`[epub] ${w.kind}`, w.family ?? w.fileId ?? w.detail),
};
const epubs = {
  fixed: await renderToEpub(doc, { ...book, layout: 'fixed' }),
  kindle: await renderToEpub(doc, { ...book, layout: 'fixed', kindlePanelView: true }),
  reflowable: await renderToEpub(doc, { ...book, layout: 'reflowable' }),
};

Ingredients

Tipografia
Comic Neue, Bangers, Zen Antique, Dela Gothic One, ZCOOL KuaiLe, ZCOOL QingKe HuangYou, Playpen Sans Arabic, Lalezar (SIL OFL 1.1)
Recursos
  • lh-arrive.jpg
  • lh-beam.jpg
  • lh-biscuit.jpg
  • lh-maya.jpg
  • lh-radio.jpg
  • Panel picture: Maya arrives at the lighthouse (Generated With Diffusion Models, original)
  • Panel picture: Tomás at the radio (Generated With Diffusion Models, original)
  • Panel picture: Maya finds the problem (Generated With Diffusion Models, original)
  • Panel picture: Biscuit asleep on the cable (Generated With Diffusion Models, original)
  • Panel picture: the lamp lit at night (Generated With Diffusion Models, original)

Elaboració

#1 · Exporta el mateix document com a EPUB

El codi és la resposta curta de dalt. renderToEpub rep els documents que imprimeix renderToPdf, de manera que les pàgines de l’EPUB són les del PDF (sortida dels còmics). Amb layout: 'fixed' i pàgines de còmic al llibre, escriu també regions.xhtml: una regió panel per vinyeta en ordre de lectura, cadascuna un rectangle en percentatge de la seva pàgina, amb les bafarades, cartel·les i onomatopeies com a regions a dins. El sentit de pas de pàgina segueix el sentit de lectura del còmic, així que les edicions japonesa i àrab passen de dreta a esquerra. kindlePanelView: true hi afegeix una zona tàctil per vinyeta i una còpia ampliada, amb les metadades que espera Kindle. La versió adaptable no té pàgines per conservar: cada vinyeta és la seva imatge, retallada com a la pàgina, i després els seus diàlegs, «Maya: Biscuit! I l’avi?», amb els noms de comics.cast.

Vinyeta 1 de la pàgina 2: a la lectura guiada, la primera regió, amb la cartel·la i la bafarada de la Maya a dins.

#2 · Incrusta les lletres que fan servir les pàgines

script.js · línies 210–239al codi complet
// For each weight and style the lettering asks for, the file loadComicFonts chose (the
// nearest one Fontsource ships), only the slices whose characters the book sets. A file that
// serves several weights is embedded once, with a weight range ('400 700').
const inRange = (range, cp) => range.split(',').some((part) => {
  const [lo, hi = lo] = part.trim().slice(2).split('-');
  return cp >= parseInt(lo, 16) && cp <= parseInt(hi, 16);
});
async function epubFonts(families, text) {
  const cps = [...new Set(text)].map((ch) => ch.codePointAt(0));
  const byFile = new Map(); // url → the face it serves
  for (const family of families) {
    const meta = await fontsourceMeta(family);
    const asks = [[400, 'normal'], [700, 'normal'], [400, 'italic'], [700, 'italic']];
    for (const [weight, style] of asks) {
      const w = meta.weights.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a),
        400);
      const s = style === 'italic' && meta.styles.includes('italic') ? 'italic' : 'normal';
      for (const { url, range } of await comicFaceFiles(family, w, s, meta, text)) {
        if (range && !cps.some((cp) => inRange(range, cp))) continue;
        const face = byFile.get(url) ?? { family, style: s, weights: new Set(), range };
        face.weights.add(weight);
        byFile.set(url, face);
      }
    }
  }
  return Promise.all([...byFile].map(async ([url, { family, style, weights, range }]) => ({
    family, style, format: 'woff2', unicodeRange: range,
    weight: weights.size > 1 ? `${Math.min(...weights)} ${Math.max(...weights)}` : [...weights][0],
    bytes: new Uint8Array(await (await fetch(url)).arrayBuffer()) })));
}

Un EPUB de maqueta fixa dibuixa el text amb les lletres que porta a dins, i una lletra que falta se substitueix per la del lector. La retolació demana rodona, negreta i cursiva; les lletres de còmic en porten menys, així que cada petició rep el fitxer que va triar loadComicFonts, i un fitxer que serveix als dos gruixos hi entra una sola vegada amb el rang '400 700'. Les lletres japoneses i xineses només porten els trossos amb els caràcters de la seva edició, cosa que deixa el llibre japonès en 1,4 MB.

#3 · Torna a llegir cada fitxer

script.js · línies 283–304al 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');
for (const [name, bytes] of Object.entries(epubs)) {
  const epub = readEpub(bytes);
  const regions = new TextDecoder().decode(epub.files.get(`${epub.root}regions.xhtml`)
    ?? new Uint8Array());
  const panels = regions.split('<li epub:type="panel">').slice(1); // one per panel
  const card = el('article', 'width: min(300px, 92vw); padding: 16px; border: 1px solid #2c3038');
  const steps = el('ol', 'margin: 8px 0; padding-left: 22px');
  steps.append(...panels.map((p, i) => el('li', '', `panel ${i + 1}: ${(p.match(
    /epub:type="(balloon|caption|sound-area|text-area)"/g) ?? []).length} text regions`)));
  const link = Object.assign(el('a', 'color: #d8a21a', `Download ${RECIPE}-${name}.epub`), {
    href: URL.createObjectURL(new Blob([bytes])), download: `${RECIPE}-${name}.epub` });
  card.append(el('h2', 'margin: 0; font-size: 15px; color: #f4f1ea', `EPUB 3 · ${name}`),
    el('p', 'margin: 4px 0 0', `${epub.layout} · ${epub.pageProgression} · `
      + `${epub.spine.length} documents · ${Math.round(bytes.length / 1024)} KB`),
    panels.length ? steps : el('p', '', 'No region navigation: the panels are text.'), link);
  shelf.append(card);
}
document.getElementById('pages').before(shelf);

readEpub obre els bytes com ho faria un lector: maqueta, sentit de pas, espina. La llista de cada targeta és la mateixa lectura guiada, llegida de regions.xhtml: cinc vinyetes i les seves regions de text, en l’ordre en què el lector les recorre. Els tres fitxers passen EPUBCheck 5.4 sense errors ni avisos en anglès, japonès i àrab.

#4 · Una maqueta, deu edicions

script.js · línies 36–41al codi complet
const [LETTERING, SFX] = t({
  en: ['Comic Neue', 'Bangers'], es: ['Comic Neue', 'Bangers'], ca: ['Comic Neue', 'Bangers'],
  ja: ['Zen Antique', 'Dela Gothic One'], zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou'],
  ar: ['Playpen Sans Arabic', 'Lalezar'], pt: ['Comic Neue', 'Bangers'],
  fr: ['Comic Neue', 'Bangers'], de: ['Comic Neue', 'Bangers'], it: ['Comic Neue', 'Bangers'],
});

Cada content.<lang>.md porta les paraules d’una edició amb els mateixos identificadors de personatge. Les regions de les vinyetes són iguals en tots els idiomes; les de les bafarades es mouen amb elles, que es retolen de nou al voltant del text de cada idioma.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 148 · A comic EPUB read panel by panel ═══════════════════
// https://postext.dev/en/cookbook/comic-epub-guided-view
// Code: MIT · Text: original (CC BY 4.0) · Pictures: generated with diffusion models
// Fonts: Comic Neue, Bangers and the faces of five editions (OFL) · Needs postext ≥ 1.65.0
//
// A short comic laid out once and exported four ways: a PDF for print, a fixed-layout EPUB
// whose region-based navigation lets a reading system step through it panel by panel, the
// same EPUB with Kindle Panel View, and a reflowable EPUB with each panel's lines as text.
// Each file is read back to list what a reader will find in it.
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, loadVerticalAlternates,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';
import { renderToEpub, readEpub } from 'https://esm.sh/postext-epub';

const LANG = 'ca'; // @lang: 'en' | 'es' | 'ca' | 'zh' | 'ar' | 'ja' | 'pt' | 'fr' | 'de' | 'it'
const RECIPE = 'comic-epub-guided-view';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: the night sea, the lighthouse red and the yellow of the captions
const palette = {
  ink: '#1b2430', // panel borders, lettering and the title page
  accent: '#b8322a', // the lighthouse red: title and sound effects
  caption: '#f4e7bf', // caption boxes
  muted: '#5f6873', // folios and the imprint
  paper: '#fdfbf6',
};
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

// #region editions: six editions, each lettered in faces for its script
const [LETTERING, SFX] = t({
  en: ['Comic Neue', 'Bangers'], es: ['Comic Neue', 'Bangers'], ca: ['Comic Neue', 'Bangers'],
  ja: ['Zen Antique', 'Dela Gothic One'], zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou'],
  ar: ['Playpen Sans Arabic', 'Lalezar'], pt: ['Comic Neue', 'Bangers'],
  fr: ['Comic Neue', 'Bangers'], de: ['Comic Neue', 'Bangers'], it: ['Comic Neue', 'Bangers'],
});
// #endregion

const comics = {
  gutter: { horizontal: mm(4), vertical: mm(3) },
  panel: { borderWidth: pt(1), borderColor: col('ink'), background: col('paper') },
  lettering: { fontFamily: LETTERING, fontSize: pt(8), color: col('ink'), inset: mm(1.5) },
  balloonStyles: [{ id: 'speech', stroke: col('ink') }, { id: 'caption', fill: col('caption'),

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

#Treu l’edició per a Kindle

La navegació per regions va a tot EPUB fix; Kindle Panel View només s’hi afegeix.

-  kindle: await renderToEpub(doc, { ...book, layout: 'fixed', kindlePanelView: true }),

#Posa coberta al llibre adaptable

-  reflowable: await renderToEpub(doc, { ...book, layout: 'reflowable' }),
+  reflowable: await renderToEpub(doc, { ...book, layout: 'reflowable',
+    cover: { bytes: imageBytes('lh-beam.jpg'), mediaType: 'image/jpeg' } }),

Errors freqüents

  • Una lletra incrustada una vegada per cada gruix al qual serveix es copiaria quatre vegades; l’edició xinesa pesava 5,3 MB abans dels rangs de gruix.

Crèdits

Text
Text original, CC BY 4.0
Imatges
  • Panel picture: Maya arrives at the lighthouse · Generated With Diffusion Models · original
  • Panel picture: Tomás at the radio · Generated With Diffusion Models · original
  • Panel picture: Maya finds the problem · Generated With Diffusion Models · original
  • Panel picture: Biscuit asleep on the cable · Generated With Diffusion Models · original
  • Panel picture: the lamp lit at night · Generated With Diffusion Models · original
Fonts
Comic Neue (SIL OFL 1.1) · Bangers (SIL OFL 1.1) · Zen Antique (SIL OFL 1.1) · Dela Gothic One (SIL OFL 1.1) · ZCOOL KuaiLe (SIL OFL 1.1) · ZCOOL QingKe HuangYou (SIL OFL 1.1) · Playpen Sans Arabic (SIL OFL 1.1) · Lalezar (SIL OFL 1.1)
SandboxPDF