31. Conversión y exportación: panorama {#31-conversión-y-exportación-panorama}

Markdown es un formato de origen, casi nunca el formato final. Un conversor transforma el texto en HTML, PDF, DOCX, EPUB, LaTeX, vídeo u otros destinos. La calidad del resultado depende de tres factores: el parser (qué dialecto entiende), las extensiones activadas y la plantilla o motor de destino.

Este capítulo ofrece el mapa general. Cada formato tiene su propio capítulo, con comandos, herramientas, limitaciones y listas de comprobación.

31.1 Mapa de exportación {#311-mapa-de-exportación}

31.2 El pipeline de conversión {#312-el-pipeline-de-conversión}

Todo conversor sigue un proceso común:

texto Markdown
   │  parser (CommonMark, GFM, Pandoc Markdown…)
   ▼
árbol de sintaxis abstracta (AST)
   │  transformaciones y filtros
   ▼
writer o renderizador (HTML, LaTeX, DOCX…)
   │  plantilla, hoja de estilo, metadatos
   ▼
documento final

Consecuencias prácticas:

• El dialecto importa: una tabla GFM puede no interpretarse con un parser CommonMark estricto.
• El AST pierde información: dos documentos con el mismo HTML pueden tener estructuras distintas.
• La plantilla manda: el mismo HTML produce PDF, EPUB o DOCX muy diferentes según el CSS o la plantilla.
• La conversión no suele ser reversible: DOCX → Markdown → DOCX cambia estilos, numeración y metadatos.

31.3 Pandoc: el conversor de referencia {#313-pandoc-el-conversor-de-referencia}

Pandoc lee y escribe decenas de formatos, admite plantillas, filtros, metadatos, citas y referencias cruzadas. Está escrito en Haskell y se distribuye como binario para Windows, macOS y Linux.

• Sitio oficial: https://pandoc.org/
• Manual: https://pandoc.org/MANUAL.html
• Descargas: https://pandoc.org/installing.html

31.3.1 Estructura de una orden {#3131-estructura-de-una-orden}

pandoc ENTRADA.md \
  -f gfm \                    # formato de lectura
  -t html5 \                  # formato de escritura
  -s \                        # documento completo
  --toc \                     # tabla de contenidos
  -o SALIDA.html

31.3.2 Metadatos {#3132-metadatos}

Pandoc lee el Front Matter YAML:

---
title: "Manual de usuario"
subtitle: "Versión 2.1"
author: "Equipo de documentación"
date: "2026-10-28"
lang: es
---

También se pueden pasar por línea de comandos:

pandoc README.md -o README.pdf \
  --metadata title="Manual" \
  --metadata author="Equipo" \
  --metadata lang=es

lang afecta a la división silábica, a las comillas tipográficas y a la etiqueta lang del HTML. En LaTeX se traduce en el paquete de idioma correspondiente.

31.3.3 Varios archivos y recursos {#3133-varios-archivos-y-recursos}

pandoc docs/00-intro.md docs/01-instalacion.md docs/02-uso.md \
  -o manual.pdf --toc --resource-path=.:docs

--resource-path indica dónde buscar imágenes. Para proyectos grandes conviene un script de composición o un documento maestro que incluya los demás.

31.3.4 Filtros {#3134-filtros}

Los filtros modifican el AST antes de escribir:

• Lua: --lua-filter=figuras.lua; no requiere instalar nada más.
• Ejecutables: --filter=pandoc-crossref; leen y escriben JSON.
• Filtros integrados: --citeproc para bibliografía.

Los filtros son código: trátalos como cualquier dependencia y revísalos antes de ejecutarlos sobre contenido de terceros.

31.3.5 Limitaciones {#3135-limitaciones}

• No todos los dialectos se interpretan igual: especifica -f gfm, -f commonmark o el formato adecuado.
• Las extensiones (notas al pie, definiciones, matemáticas) deben estar activadas en el lector correspondiente.
• La conversión no es bidireccional sin pérdidas.
• La salida PDF depende de fuentes y paquetes instalados.
• Algunos writers no admiten todas las estructuras (por ejemplo, RTF y ciertos tipos de tablas o notas).

31.4 Cómo elegir el destino {#314-cómo-elegir-el-destino}

31.5 Criterios de calidad {#315-criterios-de-calidad}

1. Fidelidad estructural: títulos, listas y tablas conservan su jerarquía.
2. Tipografía: fuentes con glifos para todos los caracteres, interlineado y márgenes correctos.
3. Accesibilidad: jerarquía de encabezados, texto alternativo, tablas con cabeceras y enlaces descriptivos.
4. Navegación: índice, anclas, enlaces internos y paginación funcionan.
5. Mantenibilidad: plantillas, estilos y scripts versionados junto al contenido.
6. Reproducibilidad: la misma orden produce el mismo resultado en otra máquina.

31.6 Errores frecuentes al exportar {#316-errores-frecuentes-al-exportar}

31.7 Lista de comprobación antes de exportar {#317-lista-de-comprobación-antes-de-exportar}

• El Markdown valida (sin vallas sin cerrar ni tablas mal formadas).
• El dialecto de entrada está especificado.
• Los encabezados siguen una jerarquía coherente.
• Las imágenes existen, tienen alt y un tamaño razonable.
• Los diagramas están pre-renderizados si el destino no los soporta.
• Los metadatos (título, autor, idioma, fecha) están completos.
• La plantilla o el CSS está versionado.
• El resultado se ha revisado en el formato final, no solo en el editor.
• Los enlaces y el índice funcionan en el archivo exportado.