Saltar al contingut principal
Recepta número 39

Receptari · Capítol 10 · Sortida i integració

PDF accessible i etiquetat (PDF/UA)

Una guia de reciclatge en PDF/UA-1 etiquetat, amb text alternatiu, cel·les de capçalera, llengua i índex enllaçat; la previsualització dibuixa les etiquetes.

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 castellà: encara no hi ha edició en català
  • Format 210 × 297 mm
  • 2 columnes, espai entre columnes de 8 mm
  • Atkinson Hyperlegible Next 10,5/15,5
  • Atkinson Hyperlegible Mono
  • Public Sans
  • 4 pàgines
  • Nivell
  • Postext 1.65.0
  • Compost en 205 ms
  • 179 línies de codi

En poques paraules

Una guia de reciclatge de quatre pàgines d'un ajuntament. Ensenya a crear un PDF que els lectors de pantalla poden seguir, amb descripcions de les imatges i taules que poden llegir en veu alta.

Què compondràs

Reciclar al barri és la guia de reciclatge d'un ajuntament inventat: quatre pàgines A4 per llegir en pantalla o imprimir a casa. La coberta, blau marí, porta els cinc contenidors sobre una vorada groga. La pàgina 2 reuneix l'índex, tres requadres i la carta de la regidora; la 3 i la 4, les dues seccions, a dues columnes en bandera. El PDF etiquetat que exporta el codi supera les comprovacions PDF/UA-1 de veraPDF, amb títols, llistes, requadres i taules en ordre de lectura, text alternatiu a la figura i cel·les de capçalera a les taules. El fitxer declara títol i llengua (es), i els marcadors i les files de l'índex són enllaços. Com que les etiquetes no s'imprimeixen, el codi les dibuixa només a la previsualització de la pàgina 3, la que veus aquí, amb un requadre numerat per bloc i el nom de la seva etiqueta.

Aquesta recepta respon a

  • Com genero un PDF accessible (etiquetat, PDF/UA) amb text alternatiu i llengua del document?
  • Com aconsegueixo les etiquetes «Figura» i «Taula» en la llengua del meu document?
  • Com afegeixo un índex que s'actualitzi sol (línies de punts, números de pàgina, autors, files de part)?
  • Com exporto un PDF de debò al navegador, amb les fonts incrustades?

La resposta curta

script.js · línies 47–70al codi complet
// renderToPdf writes a tagged PDF by default: the tag tree follows the headings, paragraphs,
// lists and boxes of the Markdown. Pictures and tables carry their own accessible text here.
const table = (id, tsv, columnWidths, caption, altText) => ({ id, typeId: 'table', kind: 'table',
  caption, altText, createdAt: 0, updatedAt: 0, // altText → the Table's /Summary
  placement: { position: 'here' }, // set under the sentence that cites it
  table: { model: { headerRowCount: 1, columnWidths, // row 0: TH cells, scope Column
    rows: parseTSV(tsv).rows.map((row) => row.map(({ content }, c) => ({ content: cell(content),
      ...(c === 0 && { isHeader: true }) }))) } } }); // column 0: TH cells, scope Row
const resources = () => [
  { id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
    svg: { fileId: 'contenedores.svg', width: FIGURE[0] * PX, height: FIGURE[1] * PX },
    caption: 'Una isla del barrio: de izquierda a derecha, amarillo, azul, verde, marrón y gris.',
    altText: 'Cinco contenedores en fila: amarillo con una botella de plástico, azul con una caja '
      + 'de cartón, verde con una botella de vidrio, marrón con un corazón de manzana y gris con '
      + 'una bolsa de basura cerrada.', createdAt: 0, updatedAt: 0 }, // → the Figure's /Alt
  table('dudas', dudas, [3, 2], 'Los residuos que más dudas dan.',
    'Once residuos y el contenedor de cada uno.'),
  table('horarios', horarios, [2.2, 4, 1.4], 'Días y horas de recogida.',
    'Qué días y desde qué hora se vacía cada contenedor.'),
  { id: 'calle', typeId: 'figure', kind: 'svg', createdAt: 0, updatedAt: 0, // the cover's row:
    svg: { fileId: 'calle.svg', width: STREET[0] * PX, height: STREET[1] * PX } }, // an artifact
];
const exportPdf = (doc) => renderToPdf(doc, { fontProvider: fontsourceProvider,
  resourceBytes: imageBytes }); // accessible and outlines default to true

Ingredients

Tipografia
Atkinson Hyperlegible Next, Atkinson Hyperlegible Mono, Public Sans (SIL OFL 1.1)
Recursos
Cap: totes les imatges es dibuixen en codi

Elaboració

#1 · La llengua i el títol del document

script.js · línies 126–127al codi complet
  locale: LANG, // → /Lang es, and "Figura", "Tabla" in the captions and the citations
  // /Title and /Author come from the frontmatter's title and author

postext-pdf escriu la llengua de les etiquetes a partir de locale, aquí /Lang es, perquè un lector de pantalla llegeixi la guia amb pronunciació espanyola; si falta, el fitxer declara en-US. El title i l'author del frontmatter de content.es.md donen el títol i l'autor del PDF, i el fitxer demana als visors que mostrin aquest títol a la barra de la finestra en lloc del nom del fitxer. El mateix locale dona als peus i a les cites els noms en espanyol: «Figura 1.1», «tabla 1.1». El text accessible de la figura i de les taules és a la resposta curta: l'altText dona la descripció alternativa de la figura (/Alt) i el resum de cada taula (/Summary), i la primera fila i la primera columna de les dues taules s'etiqueten com a cel·les de capçalera.

#2 · Un sol esquema, i una banda de coberta amb el títol i res més

script.js · línies 74–104al codi complet
const [BAND, COVER] = [54, 176]; // mm from the trim top to the foot of each band
const band = (height) => ({ kind: 'box', id: 'band', style: { backgroundColor: col('navy') },
  placement: { ...at('bleed', 'top-left'), size: { width: 'fill', height: mm(height) } } });
const display = (size, hue) => face('Public Sans', 800, size, { lineHeight: 1, color: col(hue) });
const section = { enabled: true, slot: { elements: [band(BAND),
  text('number', '{number}', display(64, 'signal'), at('container', 'top-left', 0, 4)),
  text('title', '{titleText}', display(28, 'paper'),
    { ...at('#number', 'right-of', 6, 3.5), size: { width: mm(130) } })] } };
// A heading design's text is tagged as the heading, so the cover's band holds only the title.
const cover = { enabled: true, minHeight: mm(COVER - TOP + 24), slot: { elements: [band(COVER),
  { kind: 'box', id: 'kerb', style: { backgroundColor: col('signal') },
    placement: { ...at('bleed', 'top-left', 0, COVER), size: { width: 'fill', height: mm(3) } } },
  { kind: 'image', id: 'bins', resourceId: 'calle', // the wheels stand on the kerb
    placement: { ...at('#kerb', 'align-bottom', SIDE), size: { width: mm(STREET[0]) } } },
  text('title', '{titleText}', display(66, 'paper'),
    { ...at('container', 'top-left', 0, 26), size: { width: mm(STREET[0]) } })] } };
const plain = (id, more) => ({ id, numbered: false, span: 'column', ...more,
  advancedDesign: { enabled: false }, fontSize: pt(26), lineHeight: pt(2 * LEAD) });
const headingStyles = [
  { id: 'portada', numbered: false, toc: false, span: 'page', advancedDesign: cover,
    layout: { layoutType: 'single' }, footer: { elements: [] } },
  plain('indice', { toc: false }), // the contents leave their own heading out
  plain('presentacion', { breakBefore: { enabled: false } }), // gotcha: style-inherits-break
];
const headings = { fontFamily: 'Public Sans', fontWeight: 800, color: col('ink'),
  levels: [ // parity 'any': a section opens the next page, whichever side it falls on
    { level: 1, numberingTemplate: '{1}', breakBefore: { enabled: true, parity: 'any' },
      span: 'page', advancedDesign: section, marginBottom: pt(LEAD) }, // 9.7 mm under the band
    { level: 2, fontWeight: 700, fontSize: pt(13.5), lineHeight: pt(LEAD), marginTop: pt(0),
      marginBottom: pt(0) }, // the line above an H2 is the paragraph's, or the resource's, gap
  ] };

L'arbre d'etiquetes pren els elements H1 i H2 dels títols del Markdown, i els marcadors del PDF surten de la mateixa llista, de manera que la coberta, l'índex, la carta i les dues seccions són de nivell 1, i els intertítols, de nivell 2. postext-pdf etiqueta cada text del disseny d'un títol dins d'aquest títol. Per això la banda de la coberta porta només el títol, i l'entradeta i el nom de l'ajuntament van a sota, com a paràgrafs. Les bandes blau marí, la vorada i la fila de contenidors són elements de disseny, i el PDF marca les caixes i les imatges de disseny com a artefactes, així que no necessiten text alternatiu i el lector de pantalla se les salta.

#3 · Un índex amb enllaços

script.js · línies 108–113al codi complet
const [NUMBER, GAP] = [6, 2.5]; // mm: the number column and the gap before a title
const toc = { levels: [{ level: 1, ...face('Public Sans', 700, 12), numberWidth: mm(NUMBER),
  numberGap: mm(GAP), marginTop: pt(LEAD / 2) }, { level: 2, indent: mm(NUMBER + GAP) }],
  unnumbered: { indent: mm(NUMBER + GAP) }, leader: { gap: mm(1.5) }, // Presentación: no number
  // The page numbers, and the leaders with them, in the text face
  pageNumber: { fontFamily: 'Atkinson Hyperlegible Next', fontWeight: 700, width: mm(8) } };

:::toc recull els H1 i els H2 amb el número de pàgina que imprimeixen, i al PDF cadascuna de les seves onze files enllaça amb el començament de la seva pàgina. Les cites :ref de la pàgina 3, «figura 1.1» i «tabla 1.1», i la de la pàgina 4, «tabla 2.1», porten a la figura i a les taules. Els números de pàgina van en la lletra del text, Atkinson Hyperlegible Next Bold, i les línies de punts prenen la lletra dels números, no la Public Sans de les entrades.

#4 · L'ordre de lectura, dibuixat a la pàgina

script.js · línies 299–319al codi complet
// An opener band's title, then each column from top to bottom; a float is read after the text
// that cites it, wherever it is painted. A paragraph continued in the next column stays one
// element, so its second part keeps its number.
const tagOf = (b) => ({ heading: `H${b.headingLevel ?? 1}`, callout: 'Div', listItem: 'LI',
  resource: b.resourceBlock?.kind === 'table' ? 'Table' : 'Figure' })[b.type] ?? 'P';
function readingOrder(page) {
  const ids = new Map(); // element → its number
  const add = (block, box) => {
    const key = block.id.replace(/-cont-\d+$/, ''); // fragments share their block's id
    if (!ids.has(key)) ids.set(key, ids.size + 1);
    return { n: ids.get(key), tag: tagOf(block), box, cont: key !== block.id };
  };
  const blocks = page.columns.flatMap((c) => c.blocks);
  const title = blocks.find((b) => b.hidden && b.type === 'heading'); // drawn by the band
  const flow = blocks.filter((b) => !b.hidden);
  for (const float of page.floats ?? []) { // after the last block up to its place in the source
    flow.splice(flow.findLastIndex((b) => b.contentIndex <= float.contentIndex) + 1, 0, float);
  }
  return [...(page.openerBand && title ? [add(title, union(page.openerBand.blocks
    .filter((b) => b.kind === 'text')))] : []), ...flow.map((b) => add(b, b.bbox))];
}

Un lector de pantalla segueix les etiquetes. renderToPdf etiqueta primer el títol de la banda i després cada columna de dalt a baix, i llegeix un flotant just després del paràgraf que el cita, es pinti on es pinti. Aquesta funció repeteix aquest ordre per numerar els requadres de la pàgina 3, i l'arbre d'estructura del PDF dona els mateixos catorze elements en el mateix ordre. La figura i les dues taules van al flux, amb placement: { position: 'here' } i una línia ::resource, perquè qui llegeix amb la vista també les trobi sota la frase que les cita. El paràgraf del vidre que continua a la segona columna conserva un sol número, el 9, perquè el PDF etiqueta les dues parts com un únic paràgraf.

#5 · Colors triats pel seu contrast

script.js · línies 15–34al codi complet
const palette = {
  ink: '#14243a', // text: 15.6:1 on white
  navy: '#173556', // bands: white type on it 12.5:1
  signal: '#f2b705', // yellow: only on navy (6.9:1) or as a fill, never as text on white
  tint: '#e8eef5', // header cells and boxes: ink on it 13.4:1
  rule: '#aebccb', // table rules
  muted: '#4a5a6e', // footer and colophon: 7.0:1 on white
  paper: '#ffffff',
};
// every colour is linked to its palette entry by id
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// 'main-color' is the id the engine's default styles link to: any default left in them is navy
const colorPalette = [...Object.entries(palette), ['main-color', palette.navy]]
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const BIN = { amarillo: '#f2b705', azul: '#1f6fc5', verde: '#2e8b4a', marron: '#8a5a2f',
  gris: '#6b7480' }; // the street bins' colours, for the pictograms and the swatches
const NAME = { amarillo: 'Amarillo', azul: 'Azul', verde: 'Verde', marron: 'Marrón', gris: 'Gris',
  punto: 'Punto limpio' }; // a table cell never shows a colour alone: its name goes beside it
const cell = (text) => (text in NAME // an unknown colour ('none') draws an empty square
  ? `:swatch{color="${BIN[text] ?? 'none'}"} ${NAME[text]}` : text);

PDF/UA-1 no comprova el color, però WCAG 2.2 demana 4,5:1 entre el text i el seu fons. La tinta dona 15,6:1 sobre blanc; la lletra blanca, 12,5:1 sobre les bandes blau marí, i el gris del peu de pàgina, 7,0:1. El groc dona 1,8:1 sobre blanc, així que només apareix sobre blau marí (6,9:1) i com a fons. Els pictogrames segueixen el 3:1 que WCAG demana als gràfics: blanc quan arriba a aquesta proporció sobre el seu contenidor i tinta sobre el groc. cell() escriu el nom de cada contenidor al costat de la seva mostra de color, i dona a la deixalleria un quadrat buit, de manera que cap indicació no depèn de distingir colors.

La recepta completa

Sandbox
// ═══ Postext Cookbook · Nº 039 · Accessible tagged PDF (PDF/UA) ═════════════════════
// https://postext.dev/en/cookbook/accessible-tagged-pdf
// Code: MIT · Text: original (CC BY 4.0) · Pictograms: generated in code (CC BY 4.0)
// Fonts: Atkinson Hyperlegible Next and Mono, Public Sans (SIL OFL 1.1) · Needs postext ≥ 1.25.0
import {
  buildDocumentWithFonts, renderPageToCanvas, registerResourceImage, parseTSV,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'es'; // @lang: the language of the sample document (this recipe is Spanish only)
const RECIPE = 'accessible-tagged-pdf';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: text colours chosen for their contrast, and never a colour without its name
const palette = {
  ink: '#14243a', // text: 15.6:1 on white
  navy: '#173556', // bands: white type on it 12.5:1
  signal: '#f2b705', // yellow: only on navy (6.9:1) or as a fill, never as text on white
  tint: '#e8eef5', // header cells and boxes: ink on it 13.4:1
  rule: '#aebccb', // table rules
  muted: '#4a5a6e', // footer and colophon: 7.0:1 on white
  paper: '#ffffff',
};
// every colour is linked to its palette entry by id
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
// 'main-color' is the id the engine's default styles link to: any default left in them is navy
const colorPalette = [...Object.entries(palette), ['main-color', palette.navy]]
  .map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } }));
const BIN = { amarillo: '#f2b705', azul: '#1f6fc5', verde: '#2e8b4a', marron: '#8a5a2f',
  gris: '#6b7480' }; // the street bins' colours, for the pictograms and the swatches
const NAME = { amarillo: 'Amarillo', azul: 'Azul', verde: 'Verde', marron: 'Marrón', gris: 'Gris',
  punto: 'Punto limpio' }; // a table cell never shows a colour alone: its name goes beside it
const cell = (text) => (text in NAME // an unknown colour ('none') draws an empty square
  ? `:swatch{color="${BIN[text] ?? 'none'}"} ${NAME[text]}` : text);
// #endregion

const TRIM = [210, 297]; // A4, the size residents print at home
const [TOP, FOOT, SIDE, LEAD] = [20, 22, 18, 15.5]; // margins in mm, not mirrored; leading in pt
const [PX, FIGURE, STREET] = [12, [83, 30], [174, 44]]; // drawings: px per mm, sizes in mm
const face = (fontFamily, fontWeight, size, more) => ({ fontFamily, fontWeight, fontSize: pt(size),
  ...more });
const at = (to, edge, x = 0, y = 0) => ({ anchor: { to, edge }, offset: { x: mm(x), y: mm(y) } });
const text = (id, content, style, placement) => ({ kind: 'text', id, content, align: 'left',
  ...style, placement }); // a heading's design wraps its text; the footer clips its own

// #region answer: the alt text and header cells the tags take from the resources
// renderToPdf writes a tagged PDF by default: the tag tree follows the headings, paragraphs,
// lists and boxes of the Markdown. Pictures and tables carry their own accessible text here.

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

#Deixa flotar la figura

Treu la col·locació i la figura 1.1 flota al peu de la primera columna de la pàgina 3. El PDF la continua llegint després del paràgraf que la cita, de manera que el dibuix li manté el número 3 i l'ordre de les etiquetes no canvia.

-  { id: 'contenedores', typeId: 'figure', kind: 'svg', placement: { position: 'here' },
+  { id: 'contenedores', typeId: 'figure', kind: 'svg',

Errors freqüents

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 →

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 →

El codi no pot validar el seu propi PDF, perquè veraPDF funciona fora del navegador. Baixa el fitxer i executa verapdf -f ua1 accessible-tagged-pdf.pdf; el PDF capturat per a aquesta pàgina passa la validació. El validador no sap si un text alternatiu descriu la seva imatge, així que escolta també la guia amb un lector de pantalla.

El colofó imprimeix l'adreça web completa perquè la guia es va escriure per a postext 1.4.1, en què un enllaç de Markdown imprimia les seves paraules sense afegir cap enllaç al PDF. Des de postext 1.10 un enllaç [texto](url) funciona al PDF i s'etiqueta com a element Link, amb les paraules enllaçades com a text.

Crèdits

Text
Text original, CC BY 4.0
Fonts
Atkinson Hyperlegible Next (SIL OFL 1.1) · Atkinson Hyperlegible Mono (SIL OFL 1.1) · Public Sans (SIL OFL 1.1)
SandboxPDF