Markdown a PDF por lotes: ZIP web, CLI, Pandoc y CI

Tres tareas comunes de lote:

1. Un Markdown → un PDF, repetido para muchos archivos: md-to-pdf *.md (CLI npm).
2. Muchos Markdown → un PDF combinado (libro, informe con capítulos): pandoc chapter*.md -o book.pdf.
3. Muchos Markdown → un PDF en cada commit: workflow de GitHub Actions con la CLI npm.

También hay una opción web: Exportación por lotes genera salidas separadas sin instalar CLI. La página /markdown-to-pdf sigue siendo útil para un documento. Elige lotes web, automatización local o PDF combinado según la entrega.

Abre Exportación por lotes, sube hasta 15 Markdown, elige PDF y ajustes comunes y ejecuta la exportación. Admite PNG, JPEG, WebP, PDF y DOCX. Es una función de pago; Creator incluye 20 ejecuciones de lotes al mes.

El ZIP contiene una salida por cada entrada correcta. Si un archivo falla, revisa su nota .error.txt en lugar de dar todo el lote por correcto. Una ejecución con al menos un archivo generado consume una ejecución del cupo. Un ZIP con 15 PDF sigue siendo una colección de 15 documentos, no un libro combinado.

Usa esta muestra como uno de los archivos. Compara título, lista y nota final con la vista previa y el PDF descargable; después inspecciona las demás salidas.

# Chapter 01: export checks

## Scope
This sample represents one source file in a multi-file export.

- Keep one output per input file
- Check every generated file
- Inspect the ZIP for error notes

> A ZIP of PDFs is different from one merged PDF.

Descargar el PDF de ejemplo

Caso simple. Tienes chapter01.md, chapter02.md, ..., y quieres chapter01.pdf, chapter02.pdf, ...

npm install -g md-to-pdf
md-to-pdf 'chapters/*.md'

Listo — por defecto escribe un .pdf junto a cada .md. Añade un stylesheet para controlar el aspecto:

md-to-pdf 'chapters/*.md' --stylesheet ./style.css

Para cientos de archivos, paraleliza:

find chapters -name '*.md' -print0 | xargs -0 -P 4 -I {} md-to-pdf '{}'

Empieza con poca concurrencia y auméntala observando CPU y memoria; cada worker puede iniciar un proceso de navegador.

Libros, informes técnicos, docs de onboarding multi-archivo.

pandoc chapter01.md chapter02.md chapter03.md -o book.pdf

pandoc chapter*.md -o book.pdf  # alphabetical order, fine if you've zero-padded

pandoc chapter*.md --toc -o book.pdf

pandoc chapter*.md --toc --top-level-division=chapter -o book.pdf

: > combined.md
for f in chapter*.md; do
  cat "$f" >> combined.md
  printf '\n\n<div style="page-break-before: always;"></div>\n\n' >> combined.md
done
md-to-pdf combined.md

Workflow de GitHub Actions que produce PDFs en cada push a main:

# .github/workflows/build-pdfs.yml
name: Build PDFs
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install -g md-to-pdf
      - run: md-to-pdf 'docs/**/*.md'
      - uses: actions/upload-artifact@v4
        with:
          name: pdfs
          path: 'docs/**/*.pdf'

Corre md-to-pdf sobre todos los Markdown bajo docs/, sube los PDFs como artefacto. Cambia a tag push para adjuntarlos a un Release.

1. Rutas de imagen rotas en el PDF combinado. Si chapter01.md referencia ./images/a.png, al concatenar la ruta se rompe. Usa rutas absolutas, embebe imágenes como data URI o usa --resource-path=. en Pandoc.
2. Front matter. En Pandoc, un bloque YAML posterior sobrescribe el mismo campo de uno anterior. Unifica los metadatos del libro; consulta las reglas de metadatos.
3. Numeración. --top-level-division=chapter cambia el tipo de división, no la política de paginación. Configúrala en el motor y la plantilla y revisa el PDF; consulta las opciones de división.
4. Fuentes Unicode y CJK. Con Pandoc y XeLaTeX define una fuente instalada, por ejemplo --pdf-engine=xelatex -V mainfont:"Source Han Serif CN". Chromium local usa fuentes de su runtime; en servicios alojados prueba los caracteres reales.
5. Memoria en lotes grandes. El renderizado con navegador consume recursos. Limita la concurrencia, vigila memoria y divide trabajos enormes en bloques reanudables.

• Un documento → /markdown-to-pdf.
• Hasta 15 archivos con ajustes comunes → lotes de pago.
• Reconstruir en cada commit → CLI en CI.
• Un libro con capítulos ordenados → Pandoc con --top-level-division=chapter --toc.
• PDF existentes con diseños distintos → combinar con pdfunite o qpdf.

Más sobre tradeoffs en comparativa de métodos y en code highlighting en PDF.

Si ya tienes PDF separados, elige ensamblaje de páginas o reescritura PDF según lo que debas conservar:

# pdfunite (poppler-utils)
pdfunite chapter01.pdf chapter02.pdf chapter03.pdf book.pdf

# or qpdf
qpdf --empty --pages chapter*.pdf -- book.pdf

# or ghostscript
gs -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=book.pdf chapter*.pdf

Usa pdfunite o qpdf para ensamblar páginas. Ghostscript pdfwrite crea un PDF nuevo; no es una concatenación sin pérdidas. Revisa fuentes, enlaces, marcadores y compresión de imágenes; consulta la documentación.

¿Puedo exportar por lotes en el navegador?

Para varios archivos, abre Exportación por lotes: es una herramienta de pago que admite hasta 15 Markdown por ejecución y descarga un ZIP con una salida por entrada. Creator incluye 20 ejecuciones al mes. PDF genera archivos separados; para un único documento combinado, usa Pandoc.

¿Cómo conservo resaltado en lote?

La CLI hereda lo que pases con --stylesheet. Mismo tema en todos. Ver Markdown a PDF con resaltado.

¿Límite del PDF combinado?

No existe un límite universal de páginas: influyen memoria, imágenes, fuentes, renderizador y lector PDF. Prueba documentos grandes representativos, define tiempos máximos en CI y divide manuales enormes.

¿Pandoc preserva Mermaid en batch?

Comprueba el renderizador; no asumas que los bloques Mermaid se convierten en diagramas. En las recetas locales, prepara imágenes o configura un pretratamiento compatible. Revisa que no falten diagramas ni estén recortados en el PDF.

La herramienta correcta depende del producto:

• Archivos separados en un ZIP → lotes de pago.
• PDF individuales por script → md-to-pdf '*.md'.
• Un libro combinado → pandoc chapter*.md --toc -o book.pdf.
• Compilación continua → GitHub Actions + CLI.
• PDF existentes → pdfunite o qpdf.

Para un grupo ocasional, empieza con lotes web y revisa el ZIP. Sus PDF no se fusionan en un documento. Si necesitas un único PDF, usa la receta ordenada de Pandoc o combina los PDF ya exportados con una herramienta específica.

Los límites y comandos anteriores se comprobaron con estas fuentes primarias actuales:

• https://pandoc.org/MANUAL.html
• https://github.com/simonhaenisch/md-to-pdf
• https://docs.github.com/en/actions

Abre MarkdownToImage, renderiza Markdown y elige el formato adecuado. Antes de automatizar un lote, prueba un documento representativo.

Inicia una exportación por lotes web.

• Elige un método PDF
• Preserva los colores al exportar