33. Exportación a PDF {#33-exportación-a-pdf}

PDF es el formato de distribución por excelencia para manuales, informes, libros y documentación que debe verse igual en cualquier dispositivo. Markdown no genera PDF directamente: hay que elegir un motor que convierta el documento y una plantilla que controle la tipografía.

33.1 Cuatro familias de motores {#331-cuatro-familias-de-motores}

33.2 Pandoc + LaTeX {#332-pandoc–latex}

Es la ruta con mejor calidad tipográfica para texto técnico con fórmulas.

pandoc manual.md -o manual.pdf \
  --pdf-engine=xelatex \
  --toc --number-sections \
  -V documentclass=report \
  -V geometry:margin=2.5cm \
  -V mainfont="DejaVu Serif" \
  -V monofont="DejaVu Sans Mono" \
  -V lang=es \
  -V fontsize=11pt \
  -V linestretch=1.15

Motores:

• xelatex: Unicode y fuentes del sistema; recomendado para español, emoji y CJK (con la fuente adecuada).
• lualatex: similar, con Lua para personalización.
• pdflatex: rápido y compatible, pero limitado con Unicode.
• context: alternativa potente, menos habitual.

33.2.1 Portada, encabezados y saltos {#3321-portada-encabezados-y-saltos}

pandoc manual.md -o manual.pdf \
  --include-in-header=cabecera.tex \
  --include-before-body=portada.tex \
  --include-after-body=colofon.tex

cabecera.tex puede cargar fancyhdr, hyperref o definir colores:

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhead[L]{Manual de usuario}
\fancyhead[R]{\thepage}

Para forzar un salto de página, incluye LaTeX crudo en el Markdown:

\newpage

Pandoc lo deja pasar al archivo .tex. Si necesitas un salto en DOCX, el mecanismo es distinto (véase el capítulo 34).

33.2.2 Código y tablas {#3322-código-y-tablas}

# Resaltado con listings
pandoc manual.md -o manual.pdf --listings

# Con minted (requiere instalar pygments y compilar con --shell-escape)
pandoc manual.md -o manual.pdf \
  --pdf-engine=xelatex \
  --include-in-header=minted.tex

Pandoc convierte las tablas a longtable cuando pueden ocupar varias páginas. Para tablas muy anchas, reduce columnas, usa texto más corto o cambia a una lista de definiciones.

33.2.3 Imágenes y figuras {#3323-imágenes-y-figuras}

![Diagrama de arquitectura](img/arquitectura.png){width=80%}

Con LaTeX, width=80% se traduce en un ancho relativo al texto. Para control en centímetros: {width=12cm}. Las imágenes deben tener resolución suficiente (al menos 150–300 ppp para impresión).

33.2.4 Matemáticas y referencias {#3324-matemáticas-y-referencias}

Pandoc convierte $...$ y $$...$$ a LaTeX nativo. Para numerar y referenciar ecuaciones, figuras o tablas, usa un filtro como pandoc-crossref:

pandoc apuntes.md -o apuntes.pdf \
  --filter=pandoc-crossref \
  --number-sections

Para bibliografía:

pandoc articulo.md -o articulo.pdf \
  --citeproc --bibliography=referencias.bib --csl=estilo.csl

El capítulo 36 amplía las referencias cruzadas y las citas.

33.3 Pandoc + WeasyPrint (HTML/CSS) {#333-pandoc–weasyprint-htmlcss}

WeasyPrint convierte HTML y CSS a PDF e implementa CSS Paged Media: márgenes, cabeceras, pies, numeración y saltos.

pandoc manual.md -o manual.pdf \
  --pdf-engine=weasyprint \
  --css=estilo-pdf.css \
  --toc

@page {
  size: A4;
  margin: 2.2cm 2cm;
  @bottom-center {
    content: counter(page);
    font-size: .85rem;
    color: #666;
  }
}

@page :first {
  margin: 0;
  @bottom-center { content: none; }
}

h1 { break-before: page; }
h2, h3 { break-after: avoid; }
table, figure, pre { break-inside: avoid; }
p { orphans: 3; widows: 3; }

Cabeceras variables con string-set:

h1 { string-set: capitulo content(); }
@page { @top-right { content: string(capitulo); } }

WeasyPrint no ejecuta JavaScript: Mermaid, KaTeX y resaltadores que dependen del navegador deben pre-renderizarse o generar HTML estático.

• Documentación: https://doc.courtbouillon.org/weasyprint/stable/
• Proyecto: https://weasyprint.org/

33.4 Chromium y md-to-pdf {#334-chromium-y-md-to-pdf}

La impresión del navegador reproduce el CSS de pantalla y admite @media print. Se puede automatizar con Chrome/Chromium en modo headless:

chrome --headless --disable-gpu \
  --print-to-pdf=manual.pdf \
  --no-pdf-header-footer \
  file:///ruta/manual.html

md-to-pdf envuelve este flujo para Markdown:

npx md-to-pdf README.md
npx md-to-pdf README.md --config-file=pdf-config.js

Ventajas: usa el mismo CSS que la web y renderiza Mermaid/KaTeX con JavaScript. Limitaciones: cabeceras y pies menos flexibles, dependencia de Chromium y resultados variables entre versiones.

• md-to-pdf: https://github.com/simonhaenisch/md-to-pdf

33.5 Typst {#335-typst}

Pandoc 3.x puede usar Typst como motor:

pandoc manual.md -o manual.pdf --pdf-engine=typst

Typst es un sistema de composición moderno, rápido y con una sintaxis más sencilla que LaTeX. Su ecosistema de paquetes es más joven, pero cubre documentos técnicos, tablas y matemáticas.

• Typst: https://typst.app/
• Documentación: https://typst.app/docs/

33.6 LibreOffice y wkhtmltopdf {#336-libreoffice-y-wkhtmltopdf}

• LibreOffice: convierte DOCX u ODT a PDF con soffice --headless --convert-to pdf manual.docx. Útil si el flujo pasa por Word o si la organización exige plantillas corporativas.
• wkhtmltopdf: usa Qt WebKit; su mantenimiento es limitado y el renderizado CSS moderno es inconsistente. Para nuevos proyectos, prefiere Chromium o WeasyPrint.

33.7 Metadatos, enlaces y accesibilidad {#337-metadatos-enlaces-y-accesibilidad}

• Título y autor: añade title y author en el Front Matter; Pandoc los pasa a hyperref en LaTeX.
• Marcadores: los encabezados generan marcadores en el PDF si el motor lo permite.
• Enlaces internos: comprueba que las anclas sobreviven a la conversión.
• Idioma: declara lang para que el lector active la voz y la división correctas.
• PDF etiquetado: la accesibilidad completa (orden de lectura, tablas etiquetadas) no es automática; requiere motores y flujos específicos.

33.7.1 PDF/UA {#3371-pdfua}

PDF/UA (ISO 14289) es la norma de accesibilidad para PDF. No basta con que el documento «se vea bien»: el archivo debe exponer su estructura para que un lector de pantalla pueda recorrerlo.

Cómo se consigue:

• LaTeX: el kernel reciente permite \DocumentMetadata{...} y el paquete tagpdf para generar estructura etiquetada. No es el comportamiento por defecto de una instalación antigua.
• HTML → PDF: algunos motores permiten generar PDF etiquetado; comprueba la versión y el resultado, porque el soporte varía.
• Ofimática: Word y LibreOffice tienen comprobadores de accesibilidad y exportación etiquetada, con resultados desiguales.
• Pandoc solo: la conversión a PDF no garantiza PDF/UA. Hay que elegir el motor y la configuración adecuados.

Validación:

1. veraPDF con el perfil PDF/UA, si está disponible en tu flujo.
2. PAC u otra herramienta de validación.
3. Comprobador de accesibilidad del editor de PDF.
4. Prueba manual con lector de pantalla: orden de lectura, tablas y figuras.
5. Revisión del texto extraído: si el orden es absurdo, la estructura no sirve.

Errores frecuentes: documento sin etiquetas, figuras sin texto alternativo, tablas sin cabeceras, idioma ausente, fuentes no incrustadas y páginas escaneadas sin OCR. Un PDF/UA técnicamente válido puede seguir siendo difícil de usar; la validación automática no sustituye la prueba con una persona.

33.7.2 Verificación antes de publicar {#3372-verificación-antes-de-publicar}

1. Abre el PDF en dos lectores distintos.
2. Comprueba el índice, los marcadores y los enlaces internos.
3. Copia texto de una tabla y de un bloque de código: ¿el orden tiene sentido?
4. Busca una palabra con tilde y otra con símbolo matemático.
5. Revisa los metadatos (título, autor, idioma).
6. Ejecuta el validador de accesibilidad si el documento lo requiere.
7. Prueba la navegación con teclado y, si es crítico, con lector de pantalla.

33.8 Problemas frecuentes {#338-problemas-frecuentes}

33.9 Lista de comprobación {#339-lista-de-comprobación}

• El motor elegido soporta los caracteres del documento.
• Márgenes, tamaño de página y fuente están definidos.
• El índice y la numeración de secciones son correctos.
• Las tablas no desbordan y se parten donde deben.
• Las imágenes tienen resolución y tamaño adecuados.
• Los diagramas están pre-renderizados.
• Los enlaces internos y las referencias funcionan.
• El idioma y los metadatos están declarados.
• Si se exige PDF/UA, el documento está etiquetado y validado.
• Las tablas tienen cabeceras y las figuras, texto alternativo.
• El PDF se ha revisado en un lector real, no solo en el editor.