Em poucas palavras
O programa de quatro páginas de um concerto ao entardecer. Mostra como salvá-lo num PDF idêntico à tela, com as fontes dentro e cada título na lista de marcadores para pular até ele.
O que você vai compor
O programa de um recital ao entardecer, Home from Sea: quatro páginas A5 para um conjunto de soprano, violoncelo e harpa. A capa é azul-petróleo noturno, com o título em Fraunces itálico dourado e fileiras de escamas de onda douradas subindo do pé. Por dentro, a ordem do programa é uma tabela com cabeçalho azul-petróleo em versais de Tenor Sans e uma linha de total com fundo tingido. As notas estão em Crimson Text justificado. As letras das três canções são poemas de Longfellow, Stevenson e Tennyson, compostos com os recuos das edições impressas. O botão Build the PDF gera o arquivo que você mandaria ao público por e-mail ou publicaria no site da sala de concertos. As quatro páginas batem linha a linha com a tela. O arquivo incorpora só os cinco arquivos de fonte que o navegador carregou, e cada título é um marcador. Para impressão em gráfica, veja o PDF pronto para impressão.
Esta receita responde a
- Como faço para exportar um PDF de verdade no navegador, com as fontes incorporadas?
- Por que as minhas quebras de linha mudam ou as palavras se sobrepõem no PDF, e como carrego as fontes corretamente?
A resposta curta
// 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)));
}
Ingredientes
- Funcionalidades
- Fontes incorporadas ao PDFExportação para PDFMarcadores do PDFFontes antes da diagramaçãoTipografia do textoMetadados do documentoCapas, folhas de rosto e colofõesAberturas desenhadasEstilos de títuloAtributos de títuloCabeços por seçãoQuebras de linha nos títulosCabeços e fóliosImagens nos designs de páginaCor do papelTipos de recurso personalizadosFiguras exatamente aquiEstilo de tabelaEstilos de parágrafoPáginas em um canvas
- Tipografia
- Crimson Text, Fraunces, Tenor Sans (SIL OFL 1.1)
- Materiais
- The seigaiha waves on the cover, drawn in code in the page’s palette (Ignacio Ferro, CC BY 4.0)
Preparo
#1 · Um download por fonte, para a página e para o PDF
O código é a resposta curta logo acima. O Postext mede cada palavra com as fontes que o navegador tem carregadas no momento da composição, e o PDF desenha cada linha onde essa diagramação a deixou. Se o PDF incorporar outro arquivo, como a instância padrão de uma fonte variável ou uma fonte substituta do sistema, cada palavra continua começando na posição medida, mas as letras têm outras larguras, e as palavras se sobrepõem ou deixam buracos. Por isso a receita baixa cada fonte uma vez só. Os bytes viram um FontFace antes da primeira composição, e o provedor de fontes passa esses mesmos bytes por decompressWoff2 para o PDF, de modo que a exportação não baixa nenhuma fonte por conta própria.
#2 · Primeiro as fontes, depois a diagramação
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() só se resolve quando todas as fontes de FONTS estão carregadas, por isso a primeira composição já mede com as fontes que o PDF vai incorporar. Ela também é a única, porque FONTS lista todas as fontes em que as páginas são compostas, e o buildDocumentWithFonts já encontra declaradas todas as fontes que procura (Carregar as fontes antes da diagramação). Essa verificação só ajuda a tela. Se faltar uma fonte em FONTS, o motor a pede ao kit, carrega o arquivo do Fontsource e refaz a diagramação sem aviso no console, mas o PDF continua recebendo a fonte mais próxima que o provedor tiver.
#3 · A exportação e a lista do que foi incorporado
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 chama onProgress em três fases: prepare depois de incorporar as fontes e a capa, pages depois de cada página e save antes de gravar o arquivo. Ele só pede ao provedor as fontes que as páginas pintam, aqui cinco. A linha de status lista os cinco arquivos que o provedor serviu, exatamente os de FONTS, e nenhuma substituta. Uma substituta denuncia uma fonte que falta em FONTS. Se você tirar a Crimson Text 600, a linha mostra Crimson Text 600 → 400 e o negrito de The Harbour Consort, na página 4, sai com peso regular. A visualização do CodePen não consegue mostrar um PDF, de modo que o offerPdf do kit troca o botão por dois links, um que abre o PDF numa nova aba e outro que o baixa (Geração de PDF).
#4 · A árvore de títulos é a árvore de marcadores
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) };
No PDF, o painel de marcadores mostra o título da capa, Programme com About the music embaixo, The texts com as três canções e The performers. Os marcadores seguem os níveis de título, por isso escolha esses níveis pensando neles: aqui, um H1 por seção e um H2 por canção. The performers tem um estilo de título próprio, um H1 sem quebra de página e sem abertura, de modo que divide a página 4 com o poema de Tennyson e ainda assim ganha um marcador de primeiro nível. O \\ que quebra em duas linhas o título da capa vira um espaço no marcador.
#5 · Título e autor a partir do frontmatter
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')),
] } },
};
A capa imprime dois valores do front matter com {author} e {subtitle}, e as propriedades do documento PDF tiram do mesmo bloco o título, Home from Sea, e o autor, The Harbour Consort. A data e o local são atributos do título da capa. O desenho atrás deles é um único SVG da largura da página, e o PDF o mantém como traçados vetoriais.
A receita completa
// ═══ 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}`);
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
#Deixe os marcadores de fora
Um folheto de uma página ou um cartaz não tem nada para marcar. Com outlines: false, o PDF fica sem marcadores e abre com a barra lateral fechada.
- outlines: true, // the default, spelled out: each heading becomes a bookmark
+ outlines: false,#Sirva você mesmo as fontes
Aponte o fetch para cópias suas dos mesmos arquivos WOFF2 estáticos, um por peso e estilo, com os nomes de arquivo do Fontsource. A página e o PDF continuam compartilhando cada download.
- 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`);Erros comuns
Erro comum
O negrito ou itálico que falta na família é simulado na tela, não no PDF
Quando um texto pede um peso ou estilo que a família não traz (um cabeçalho de tabela em negrito numa fonte de títulos de um estilo só, itálico numa sem serifa sem itálicos), o navegador o sintetiza no canvas e no HTML, engrossando ou inclinando o redondo com as mesmas larguras. Um PDF só incorpora fontes reais, então nele sai a fonte mais próxima que o provedor entregar, sem engrossar nem inclinar. Ponha na sua lista de fontes só as que a família traz e ajuste cada estilo a elas, por exemplo com tableStyle.headerBold: false. Fontes incorporadas ao PDF →
Erro comum
Os arquivos do Fontsource cobrem letras, não símbolos
O kit incorpora o arquivo latin do Fontsource de cada fonte e, quando o texto usa esses caracteres, o arquivo latin-ext para č, ł, † e o arquivo greek para α, χ (em uma família que o tenha: Lora e Gelasio não têm), na tela e no PDF. Símbolos como →, ≈, ✓ e ★ não estão em nenhum desses arquivos e somem no PDF: desenhe-os, componha-os como matemática ou escolha uma fonte cujos arquivos os tenham. Fontes incorporadas ao PDF →
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 →
Liste em FONTS todas as fontes em que as páginas são compostas, inclusive o negrito e o itálico do texto. Se faltar um, a tela continua certa, porque o kit carrega a fonte sem avisar, mas o PDF imprime a fonte mais próxima que o provedor tiver, e só as substitutas na linha de status revelam a troca.
Use arquivos estáticos, um por peso e estilo. De um WOFF2 variável, o PDF incorpora só a instância padrão, e um trecho em negrito sairia com peso regular (Por que um provedor de fontes?).
Créditos
- Receita
- Ignacio Ferro
- Texto
- “The Tide Rises, the Tide Falls”, with its indents, as printed in The Complete Poetical Works of Henry Wadsworth Longfellow · Henry Wadsworth Longfellow · domínio público
- “Requiem”, with the indents and italics of the first edition of Underwoods (1887) · Robert Louis Stevenson · domínio público
- “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 · domínio público
- The programme, the notes on the music, the performers and the colophon · Ignacio Ferro · CC BY 4.0
- Imagens
- The seigaiha waves on the cover, drawn in code in the page’s palette · Ignacio Ferro · CC BY 4.0
- Fontes
- Crimson Text (SIL OFL 1.1) · Fraunces (SIL OFL 1.1) · Tenor Sans (SIL OFL 1.1)
- Código
- MIT, como o Postext
Editar este texto ↗ (abre em uma nova aba)Pasta da receita no GitHub ↗ (abre em uma nova aba)


