Saltar al contingut principal
Recepta número 25

Receptari · Capítol 10 · Sortida i integració

Un PDF de debò amb les mateixes fonts incrustades

Un programa de mà exportat a PDF. Cada font es baixa un sol cop, per a FontFace i per al PDF, i cada títol esdevé un marcador.

En aquesta pàgina
Sortida
Canvas · PDF
Nivell
Intermedi
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 anglès: encara no hi ha edició en català
  • Format 148 × 210 mm
  • 1 columna
  • Crimson Text 10/13,3
  • Fraunces
  • Tenor Sans
  • 4 pàgines
  • Nivell
  • Postext 1.57.1
  • Compost en 54 ms
  • 180 línies de codi

En poques paraules

El programa de quatre pàgines d'un recital al capvespre. Ensenya a desar-lo com un PDF idèntic a la pantalla, amb les fonts a dins i cada títol a la llista de marcadors per saltar-hi.

Què compondràs

El programa de mà, en anglès, d'un recital al capvespre, Home from Sea: quatre pàgines A5 per a soprano, violoncel i arpa. La coberta és blau petroli, amb el títol en Fraunces cursiva daurada i files d'escates d'ones daurades que pugen des del peu. A dins, l'ordre del programa és una taula amb la capçalera blava en versals de Tenor Sans i el total sobre fons clar. Les notes van en Crimson Text justificat, i els poemes de les tres cançons, de Longfellow, Stevenson i Tennyson, conserven els sagnats de les edicions impreses. El botó Build the PDF genera el fitxer que enviaries al públic o penjaries al web de la sala. Les seves pàgines coincideixen línia a línia amb la pantalla. Incrusta només les cinc fonts que va carregar el navegador, i cada títol és un marcador. Per a impremta, mira el PDF amb sang i CMYK.

Aquesta recepta respon a

  • Com exporto un PDF de debò al navegador, amb les fonts incrustades?
  • Per què canvien els meus talls de línia o se solapen les paraules al PDF, i com carrego bé les fonts?

La resposta curta

script.js · línies 15–51al codi complet
// Hook-up: `await registerFaces()` before the first build; `renderToPdf(doc, { fontProvider })`.
const files = new Map(); // 'crimson-text-latin-600-normal' → its WOFF2 (gotcha: latin-subset)
function fontFile(family, weight, style) {
  const id = family.toLowerCase().replaceAll(' ', '-'), file = `${id}-latin-${weight}-${style}`;
  if (!files.has(file)) {
    files.set(file, fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${file}.woff2`)
      .then((res) => {
        if (!res.ok) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        return res.arrayBuffer();
      }));
  }
  return files.get(file);
}
const facesOf = (family) => (FONTS[family] ?? []).map((spec) =>
  ({ spec, weight: parseInt(spec, 10), style: spec.endsWith('i') ? 'italic' : 'normal' }));

// The screen: a FontFace per face, from those bytes, before the first build.
const registerFaces = () => Promise.all(Object.keys(FONTS).flatMap((family) =>
  facesOf(family).map(async ({ weight, style }) => {
    const face = new FontFace(family, await fontFile(family, weight, style),
      { weight: `${weight}`, style });
    document.fonts.add(await face.load());
  })));

// The PDF: the same bytes as TrueType. renderToPdf asks for each face the pages paint and no
// other. A face FONTS lacks gets the closest one it has, and is logged as a stand-in: the
// status line should list none.
const embedded = new Set(), standIns = new Set(); // shown once the PDF is ready
async function fontProvider(family, weight, style) {
  if (!FONTS[family]) throw new Error(`${family} is not in FONTS: no page was set in it`);
  const cost = (f) => (f.style === style ? 0 : 1000) + Math.abs(f.weight - weight);
  const best = facesOf(family).reduce((a, b) => (cost(b) < cost(a) ? b : a));
  const asked = `${weight}${style === 'italic' ? 'i' : ''}`;
  embedded.add(`${family} ${best.spec}`);
  if (asked !== best.spec) standIns.add(`${family} ${asked} → ${best.spec}`);
  return decompressWoff2(new Uint8Array(await fontFile(family, best.weight, best.style)));
}

Ingredients

Tipografia
Crimson Text, Fraunces, Tenor Sans (SIL OFL 1.1)
Recursos
  • The seigaiha waves on the cover, drawn in code in the page’s palette (Ignacio Ferro, CC BY 4.0)

Elaboració

#1 · Una baixada per font (pes i estil), per a la pàgina i per al PDF

El codi és la resposta curta de més amunt. Postext mesura cada paraula amb les fonts que el navegador té carregades en compondre, i el PDF dibuixa cada línia on la va deixar aquesta composició. Si el PDF incrusta un altre fitxer, com la instància per defecte d'una font variable o una font de reserva del sistema, cada paraula continua al seu lloc, però les lletres tenen una altra amplada, de manera que les paraules se superposen o deixen buits. Per això la recepta baixa cada font un sol cop. Amb els seus bytes es crea un FontFace abans de la primera composició, i el proveïdor de fonts passa aquests mateixos bytes per decompressWoff2 per al PDF, de manera que l'exportació no baixa cap font.

#2 · Primer les fonts, després la composició

script.js · línies 363–367al codi complet
await registerFaces(); // the answer: every face in FONTS, from its own bytes
await loadSvg('cover.svg', coverArt(PAGE.width, PAGE.height, WAVES));
// Every face is declared by now; one FONTS forgot would come from Fontsource, for the screen only.
const doc = await buildDocumentWithFonts({ markdown, resources }, config(), kitFonts(FONTS));
showPages(doc, { title: 'Home from Sea · a recital programme' });

registerFaces() no es resol fins que s'han carregat totes les fonts de FONTS, així que la primera composició ja mesura amb les fonts que incrustarà el PDF. No cal una segona, perquè FONTS enumera totes les fonts amb què es componen les pàgines, i buildDocumentWithFonts ja troba declarades totes les fonts que busca (Carregar les fonts abans de compondre). Aquesta comprovació només serveix per a la pantalla. Si a FONTS li falta una font, el motor la demana al kit, carrega el fitxer de Fontsource i torna a compondre sense avisar a la consola, però el PDF rep igualment la font més propera de les que té el proveïdor.

#3 · L'exportació i la llista del que ha incrustat

script.js · línies 371–386al codi complet
const bar = Object.assign(document.createElement('progress'), { max: 1, value: 0 });
const list = (faces) => [...faces].join(', ') || 'none';
offerPdf(() => {
  document.getElementById('pt-actions').prepend(bar);
  return renderToPdf(doc, {
    fontProvider, // the answer: the page's own font files
    resourceBytes: imageBytes, // the cover drawing, as vector paths
    outlines: true, // the default, spelled out: each heading becomes a bookmark
    onProgress: ({ phase, pages, totalPages }) => {
      bar.value = pages / totalPages;
      const says = { prepare: 'fonts and cover embedded', pages: `page ${pages} of ${totalPages}`,
        save: `embedded: ${list(embedded)} · stand-ins: ${list(standIns)}` };
      kitStatus(`PDF · ${says[phase]}`);
    },
  });
}, `${RECIPE}.pdf`);

renderToPdf crida onProgress en tres fases: prepare quan ja ha incrustat les fonts i la coberta, pages després de cada pàgina i save abans d'escriure el fitxer. Només demana al proveïdor les fonts que pinten les pàgines, aquí cinc. La línia d'estat enumera els cinc fitxers que va servir el proveïdor, que són exactament els de FONTS, i cap substituta. Una substituta delata una font que falta a FONTS. Si treus Crimson Text 600, la línia mostra Crimson Text 600 → 400 i la negreta de The Harbour Consort, a la pàgina 4, surt amb el gruix normal. La previsualització de CodePen no pot mostrar un PDF, així que offerPdf, del kit, canvia el botó per dos enllaços: un obre el PDF en una altra pestanya i l'altre el baixa (Generació de PDF).

#4 · L'arbre de títols és l'arbre de marcadors

script.js · línies 108–116al codi complet
const headings = { fontFamily: 'Fraunces', fontWeight: 300, color: col('band'),
  marginTop: pt(0), marginBottom: pt(0), // a two-line H2 carries its own space above
  levels: [ // a section opens on the next page, left or right: a programme has no blank pages
    { level: 1, breakBefore: { enabled: true, parity: 'any' }, advancedDesign: opener },
    { level: 2, ...H2 },
  ] };
// The performers: a top-level bookmark, no break, no opener (gotcha: style-inherits-break).
const aside = { id: 'aside', breakBefore: { enabled: false }, advancedDesign: { enabled: false },
  ...H2, marginTop: pt(LEAD) };

Al tauler de marcadors del PDF apareixen el títol de la coberta, Programme amb About the music a sota, The texts amb les tres cançons i The performers. Els marcadors reprodueixen els nivells de títol, així que l'índex del PDF es decideix en triar aquests nivells: aquí, un H1 per secció i un H2 per cançó. The performers té un estil d'encapçalament propi, un H1 sense salt de pàgina ni obertura, de manera que comparteix la pàgina 4 amb el poema de Tennyson i tot i així té un marcador de primer nivell. El \\ que parteix en dos el títol de la coberta queda com un espai al marcador.

#5 · Títol i autor des del frontmatter

script.js · línies 80–93al codi complet
const cover = {
  id: 'cover', span: 'page', header: { elements: [] }, footer: { elements: [] },
  advancedDesign: { enabled: true, slot: { elements: [
    { kind: 'image', id: 'night', resourceId: 'cover',
      placement: { anchor: { to: 'bleed', edge: 'top-left' }, size: { width: 'fill' } } },
    text('consort', '{author}', at('page', 'top', 18), label(8.5, 'gilt')),
    text('title', '{titleText}', at('page', 'top', 26, 120), // the \\ in the heading breaks it
      { ...title(68), lineHeight: 0.95, color: col('gilt') }),
    text('subtitle', '{subtitle}', at('page', 'top', 75, 66), { fontFamily: 'Crimson Text',
      italic: true, fontSize: pt(12.5), lineHeight: 1.25, color: col('foam') }),
    text('when', '{attr.when}', at('page', 'top', 91), label(LABEL, 'foam')),
    text('where', '{attr.where}', at('page', 'top', 96), label(LABEL, 'foam')),
  ] } },
};

La coberta imprimeix dos valors del frontmatter amb {author} i {subtitle}, i el PDF en pren el títol, Home from Sea, i l'autor, The Harbour Consort, per a les propietats del document. La data i el lloc són atributs del títol de la coberta. El dibuix del darrere és un sol SVG de l'amplada de la pàgina, i el PDF el conserva com a traçats vectorials.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 025 · A real PDF with the same fonts embedded ═══════════
// https://postext.dev/en/cookbook/pdf-with-embedded-fonts
// Code: MIT · Text: notes original (CC BY 4.0), poems in the public domain · Cover: drawn in code
// Fonts: Crimson Text, Fraunces, Tenor Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocumentWithFonts, 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 = 'pdf-with-embedded-fonts';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region answer: one download per face: the layout measures it, the PDF embeds it
// Hook-up: `await registerFaces()` before the first build; `renderToPdf(doc, { fontProvider })`.
const files = new Map(); // 'crimson-text-latin-600-normal' → its WOFF2 (gotcha: latin-subset)
function fontFile(family, weight, style) {
  const id = family.toLowerCase().replaceAll(' ', '-'), file = `${id}-latin-${weight}-${style}`;
  if (!files.has(file)) {
    files.set(file, fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${file}.woff2`)
      .then((res) => {
        if (!res.ok) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
        return res.arrayBuffer();
      }));
  }
  return files.get(file);
}
const facesOf = (family) => (FONTS[family] ?? []).map((spec) =>
  ({ spec, weight: parseInt(spec, 10), style: spec.endsWith('i') ? 'italic' : 'normal' }));

// The screen: a FontFace per face, from those bytes, before the first build.
const registerFaces = () => Promise.all(Object.keys(FONTS).flatMap((family) =>
  facesOf(family).map(async ({ weight, style }) => {
    const face = new FontFace(family, await fontFile(family, weight, style),
      { weight: `${weight}`, style });
    document.fonts.add(await face.load());
  })));

// The PDF: the same bytes as TrueType. renderToPdf asks for each face the pages paint and no
// other. A face FONTS lacks gets the closest one it has, and is logged as a stand-in: the
// status line should list none.
const embedded = new Set(), standIns = new Set(); // shown once the PDF is ready
async function fontProvider(family, weight, style) {
  if (!FONTS[family]) throw new Error(`${family} is not in FONTS: no page was set in it`);
  const cost = (f) => (f.style === style ? 0 : 1000) + Math.abs(f.weight - weight);
  const best = facesOf(family).reduce((a, b) => (cost(b) < cost(a) ? b : a));
  const asked = `${weight}${style === 'italic' ? 'i' : ''}`;
  embedded.add(`${family} ${best.spec}`);

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

#Prescindeix dels marcadors

Un full solt o un cartell no necessiten marcadors, i sense marcadors el PDF s'obre amb la barra lateral tancada.

-    outlines: true, // the default, spelled out: each heading becomes a bookmark
+    outlines: false,

#Serveix tu les fonts

Canvia l'URL de Fontsource per la de les teves còpies dels mateixos fitxers WOFF2 estàtics, un per gruix i estil, amb els noms que fa servir Fontsource. La pàgina i el PDF continuen compartint cada baixada.

-    files.set(file, fetch(`https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/files/${file}.woff2`)
+    files.set(file, fetch(`/fonts/${file}.woff2`)
       .then((res) => {
-        if (!res.ok) throw new Error(`Fontsource has no ${family} ${weight} ${style}`);
+        if (!res.ok) throw new Error(`No font file ${file}.woff2`);

Errors freqüents

Error freqüent

La negreta o la cursiva que la família no porta se simula a la pantalla, no al PDF

Quan un text demana un pes o un estil que la seva família no porta (una capçalera de taula en negreta amb una font de retolació d'un sol estil, cursiva en una sans sense cursives), el navegador el sintetitza al canvas i a l'HTML: engruixeix o inclina la rodona amb les mateixes amplades. Un PDF només incrusta fonts reals, així que allà s'imprimeix la font més propera que doni el proveïdor, sense engruixir ni inclinar. Posa a la llista de fonts només les que la família porta i ajusta cada estil a aquestes, per exemple amb tableStyle.headerBold: false. Fonts incrustades al PDF →

Error freqüent

Els fitxers de Fontsource cobreixen lletres, no símbols

El kit incrusta el fitxer latin de Fontsource de cada font i, quan el text els fa servir, el seu fitxer latin-ext per a č, ł, † i el seu fitxer greek per a α, χ (en una família que en tingui: Lora i Gelasio no), a la pantalla i al PDF. Símbols com →, ≈, ✓ i ★ no són a cap d'aquests fitxers i falten al PDF: dibuixa'ls, escriu-los com a matemàtiques o tria una font els fitxers de la qual els tinguin. Fonts incrustades al PDF →

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 →

Enumera a FONTS totes les fonts amb què es componen les teves pàgines, també la negreta i la cursiva del text. Si n'oblides una, a la pantalla no ho notaràs, perquè el kit la carrega sense avisar; el PDF, en canvi, imprimeix la font més propera que tingui el proveïdor, i només ho delaten les substitutes de la línia d'estat.

Fes servir fitxers estàtics, un per gruix i estil. D'un WOFF2 variable només s'incrusta la instància per defecte, així que una negreta sortiria amb el gruix normal (Per què un proveïdor de fonts?).

Crèdits

Text
  • “The Tide Rises, the Tide Falls”, with its indents, as printed in The Complete Poetical Works of Henry Wadsworth Longfellow · Henry Wadsworth Longfellow · domini públic
  • “Requiem”, with the indents and italics of the first edition of Underwoods (1887) · Robert Louis Stevenson · domini públic
  • “Crossing the Bar”, with its indented short lines, from the first edition of Demeter and Other Poems (1889), in the proofread Wikisource transcription · Alfred Tennyson · domini públic
  • The programme, the notes on the music, the performers and the colophon · Ignacio Ferro · CC BY 4.0
Imatges
  • The seigaiha waves on the cover, drawn in code in the page’s palette · Ignacio Ferro · CC BY 4.0
Fonts
Crimson Text (SIL OFL 1.1) · Fraunces (SIL OFL 1.1) · Tenor Sans (SIL OFL 1.1)
SandboxPDF