Cómo convertir varios archivos Markdown a PDF en lote

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.

El /markdown-to-pdf del navegador es para un archivo; los lotes necesitan CLI. Esta guía recorre los tres escenarios con comandos copiables y trampas.

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:

ls chapters/*.md | xargs -P 4 -I {} md-to-pdf {}

-P 4 corre cuatro PDFs en paralelo. Más de 4-8 te limita el coste de levantar Chromium.

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  # alfabético, ok si tienes ceros a la izquierda

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

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

echo "" > combined.md
for f in chapter*.md; do
  cat "$f" >> combined.md
  echo -e "\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: 20
      - 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. Conflictos de front-matter. Cada .md puede tener su YAML. Pandoc toma el primero; md-to-pdf por archivo lee el suyo. Quita el front-matter antes de concatenar si choca.
3. Números de página se reinician entre capítulos. Pandoc lo maneja con --top-level-division=chapter; cat-and-convert no (los números son continuos, lo habitual para un libro).
4. Fuentes Unicode / CJK. Para chino/japonés/coreano: Pandoc con XeLaTeX necesita --pdf-engine=xelatex -V mainfont:"Source Han Serif CN". Las herramientas Chromium headless (md-to-pdf, /markdown-to-pdf) heredan la pila de fuentes del sistema.
5. Memoria en lotes grandes. 500+ archivos con md-to-pdf arranca Chromium cientos de veces. Usa xargs -P para paralelizar, pero limita la concurrencia al número de cores.

• Un archivo ocasional → /markdown-to-pdf. Más rápido que instalar npm.
• Mismo template, decenas de archivos, una vez → md-to-pdf CLI.
• Mismo template, muchos archivos, en cada commit → CLI en CI.
• Libros, informes, multi-capítulo → Pandoc con --top-level-division=chapter --toc.
• Templates heterogéneos por capítulo → PDFs por archivo (Escenario 1) y luego pdfunite o qpdf.

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

Si ya generaste PDFs separados y solo quieres concatenar sin re-renderizar:

pdfunite chapter01.pdf chapter02.pdf chapter03.pdf book.pdf
qpdf --empty --pages chapter*.pdf -- book.pdf
gs -sDEVICE=pdfwrite -dNOPAUSE -dBATCH -sOutputFile=book.pdf chapter*.pdf

Sin re-render es sin pérdida y rápido (menos de un segundo para 100 archivos).

¿Puedo batch con el /markdown-to-pdf web?

La web es de archivo único. Para lotes, CLI; para uso puntual, web.

¿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?

Funcionalmente ilimitado — hemos visto 5000 páginas funcionar. Práctico: lectores PDF se ralentizan tras ~1000 páginas, adjuntos de email caben en 25 MB. Doc enormes, divide en volúmenes.

¿Hay API de batch?

Sí — nuestra Markdown to Image API soporta format=pdf, scriptable desde cualquier lenguaje con HTTP.

¿Pandoc preserva Mermaid en batch?

No nativamente. Necesita pandoc-mermaid-filter o convertir Mermaid a SVG primero.

La herramienta correcta depende del producto:

• 1 a 1 PDF → md-to-pdf '*.md'
• N a 1 libro → pandoc chapter*.md --toc -o book.pdf
• Build continuo → GitHub Actions + npm CLI
• Concatenar PDFs existentes → pdfunite o qpdf

Para un lote único sin nada instalado, el camino más fácil es: web /markdown-to-pdf por archivo, luego pdfunite.