Convertir Markdown a Word por línea de comandos (Pandoc)

Si quiere convertir Markdown a Word desde la línea de comandos, la respuesta es pandoc, y todo el trabajo cabe en una línea:

pandoc report.md -f gfm -o report.docx

Ese comando cubre la mayoría de los documentos. Lo que los tutoriales de una línea no cuentan es dónde deja de funcionar — y parte de lo que se ha escrito sobre los límites de pandoc está, sencillamente, desactualizado. Ejecuté pandoc 3.7.0.2 sobre un documento de prueba cargado de tablas, listas de tareas, ecuaciones LaTeX y un diagrama Mermaid, y después descomprimí el .docx resultante para inspeccionar qué salió en realidad. Algunos resultados me sorprendieron.

Esta guía recorre la instalación, los comandos que merece la pena conocer, el estilo del DOCX, la conversión por lotes y — a partir de esa prueba — un mapa honesto de dónde se rompe pandoc y cuándo un convertidor online es la mejor opción.

👉 Saltar a los resultados de la prueba | Ir a la comparativa CLI vs online

Instalar Pandoc

Pandoc es un único binario con instaladores para todas las plataformas principales:

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc (o el instalador MSI)
• Debian/Ubuntu: sudo apt install pandoc

Una advertencia antes de fiarse de un paquete de sistema antiguo: los repositorios de las distribuciones suelen incluir versiones de pandoc con años de retraso. Ubuntu LTS ha distribuido la 2.x durante mucho tiempo, mientras que la línea de versiones actual es la 3.x — y como verá más abajo, la antigüedad de la versión cambia qué se convierte limpiamente. Compruebe la suya con pandoc --version.

La conversión básica, explicada

El comando mínimo funciona, pero en proyectos reales tres opciones hacen casi todo el trabajo pesado:

pandoc report.md -f gfm -o report.docx --toc

¿Por qué -f gfm en lugar del dialecto Markdown por defecto de pandoc? Porque el Markdown que la mayoría escribe hoy — en los README de GitHub, en las salidas de ChatGPT y Claude, en las exportaciones de Notion — es GFM. El dialecto por defecto de pandoc es más académico: habilita notas al pie y citas, pero interpreta algunas construcciones de otro modo. Si su fuente viene de un asistente de IA o de una herramienta de desarrollo, gfm es el lector más seguro.

Nota sobre fórmulas: con el lector GFM, las matemáticas en $...$ y $$...$$ simplemente funcionan en un pandoc actual. Las ecuaciones se convierten en ecuaciones nativas de Word, no en imágenes. Volveremos sobre esto más abajo, porque es el comportamiento de pandoc peor contado de toda la web.

Dar estilo a la salida con un documento de referencia

Un DOCX generado por pandoc se abre en Word con un estilo genérico. Si el documento tiene que ajustarse a una plantilla corporativa, eso no se arregla con opciones: se usa un documento de referencia (reference-doc).

El flujo tiene tres pasos:

1. Genere la plantilla por defecto de pandoc como punto de partida:

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. Abra custom-reference.docx en Word y edite los estilos — Título 1, Normal, Tabla, bloques de código. El contenido de texto de este archivo se ignora; solo se conservan los estilos y la configuración de página.

3. Convierta aplicando la plantilla:

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

El manual de pandoc documenta qué nombres de estilo se respetan. El modelo mental que lo hace encajar: usted no está dando estilo a un documento, está enseñándole a pandoc los estilos de Word de su organización una sola vez, para reutilizarlos en cada conversión.

Convertir varios archivos por lotes

Aquí es donde la línea de comandos gana de verdad a cualquier herramienta web. Convertir una carpeta entera:

Bash (macOS/Linux):

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell (Windows):

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

Y como pandoc es una única dependencia, encaja en CI sin ceremonia alguna. Un paso de GitHub Actions que regenera copias en Word de su documentación en cada push tiene este aspecto:

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

Hay equipos que usan este patrón para mantener un espejo en Word de una wiki en Markdown, para revisiones de cumplimiento o entregables de cliente. Si convierte el mismo conjunto de archivos más de dos veces, el script se amortiza de inmediato.

Dónde Pandoc alcanza sus límites (probado en 3.7)

Esta es la prueba que hice. Un solo archivo Markdown con una tabla, una lista de tareas, matemáticas en línea ($E = mc^2$), una ecuación en display de varias líneas, un diagrama de flujo Mermaid y un bloque de alerta GFM. Convertido con pandoc 3.7.0.2; después descomprimí el .docx y leí word/document.xml directamente. Tres hallazgos.

Las matemáticas funcionan mejor de lo que le han contado

El XML del documento contiene dos bloques <m:oMath> — uno por ecuación. Eso es OMML, el formato nativo de ecuaciones de Word. Ambas ecuaciones son totalmente editables en el editor de ecuaciones de Word, se renderizan con calidad de imprenta y sobreviven al copiar y pegar en otros documentos de Office.

Esto contradice una afirmación que todavía circula en tutoriales antiguos (y que, hasta hace poco, aparecía en una de nuestras propias guías): que el LaTeX complejo se rasteriza en imágenes. En un pandoc actual, no ocurre. Las matemáticas LaTeX estándar — fracciones, sumatorios, letras griegas, subíndices — se convierten en ecuaciones nativas sin configurar nada.

El límite honesto: pandoc resuelve la sintaxis matemática LaTeX estándar, no LaTeX arbitrario. Las macros \newcommand personalizadas, las figuras TikZ y los entornos que dependen de paquetes no harán el viaje. Y si su distribución venía con pandoc 2.x, el comportamiento difiere — compruebe pandoc --version antes de culpar a la herramienta.

Mermaid es el verdadero punto de ruptura

El diagrama de flujo Mermaid no se convirtió en un diagrama. Llegó como texto monoespaciado literal — el código fuente flowchart LR en crudo, con formato de bloque de código. El XML del documento muestra cero objetos de dibujo.

Esto importa más ahora que hace cinco años, porque a los asistentes de IA les encanta Mermaid. Pida a ChatGPT o a Claude un esquema de arquitectura y hay muchas probabilidades de que la respuesta incluya un bloque de código mermaid. Convierta esa conversación con pandoc y su documento Word contendrá algo que parece código fuente olvidado. Si ese es su flujo de trabajo, nuestra guía sobre exportar la salida de ChatGPT a Word cubre los detalles específicos de la IA.

Existe un arreglo por CLI: mermaid-filter, un filtro de pandoc que renderiza los diagramas durante la conversión. Funciona, pero sopese la instalación con honestidad — es un paquete npm que arrastra un Chromium headless vía Puppeteer, y la invocación pasa a ser pandoc -F mermaid-filter .... Para un pipeline de documentación que convierte diagramas a diario, ese coste se amortiza. Para un informe que se entrega esta tarde, es un rodeo.

Pequeñas pérdidas de fidelidad en los bordes

Dos hallazgos más discretos de la misma prueba. Los bloques de alerta GFM (> [!NOTE]) conservan su texto pero pierden el tratamiento de aviso coloreado — en Word se leen como citas en bloque corrientes. Y los elementos de las listas de tareas llegan como texto de lista plano, no como controles de casilla de verificación de Word. Ninguno de los dos rompe un documento; ambos aplanan un formato que el autor probablemente eligió a propósito. Si su conversión falla de otras maneras, hemos catalogado los fallos frecuentes en problemas comunes de conversión de Markdown.

¿Línea de comandos o convertidor online?

Después de esas pruebas, este es el marco de decisión que yo usaría de verdad:

Ambas rutas son legítimas. Pandoc se gana su sitio en cualquier pipeline recurrente. Para el caso puntual de «necesito esto en .docx en los próximos cinco minutos» — sobre todo si hay Mermaid de por medio — un convertidor online gratuito de Markdown a Word le entrega un documento limpio con las ecuaciones y los diagramas renderizados, sin instalar nada.

Preguntas frecuentes

P: ¿Puedo convertir Markdown a Word sin instalar nada?
R: Desde la línea de comandos, no — pandoc requiere instalación. Si instalar software no es una opción, los convertidores en el navegador son la vía práctica; la conversión ocurre en el servidor y usted descarga el .docx terminado.

P: ¿Pandoc convierte las matemáticas LaTeX en ecuaciones reales de Word?
R: Sí. En mi prueba con pandoc 3.7.0.2, tanto las matemáticas en línea como las de display se convirtieron en ecuaciones OMML nativas, editables en el editor de ecuaciones de Word. Las excepciones: versiones muy antiguas de pandoc y macros LaTeX personalizadas.

P: ¿Por qué mi diagrama Mermaid aparece como código en Word?
R: Pandoc trata un bloque de código mermaid como código literal — no renderiza diagramas. O añade mermaid-filter a su pipeline (requiere Node.js) o usa un convertidor con renderizado Mermaid integrado.

P: ¿Cómo conservo las fuentes y estilos de encabezado de mi empresa?
R: Use --reference-doc=template.docx. Edite los estilos de esa plantilla una sola vez en Word; pandoc los aplica en cada conversión. El contenido de la plantilla se ignora, solo se trasladan los estilos.

P: ¿Cuál es la diferencia entre -f markdown y -f gfm?
R: markdown es el dialecto extendido propio de pandoc (notas al pie, citas); gfm coincide con lo que producen GitHub, ChatGPT y la mayoría de las herramientas modernas — tablas, listas de tareas, tachado. Para Markdown generado por IA o escrito por desarrolladores, gfm da menos sorpresas.

P: ¿Puede pandoc convertir Word de vuelta a Markdown?
R: Sí — invierta los argumentos: pandoc report.docx -o report.md. El viaje de ida y vuelta pierde parte del formato propio de Word (cuadros de texto, comentarios), así que trátelo como una migración de contenido, no como un ciclo sin pérdidas.

Recursos relacionados

• La guía completa de Markdown a Word: el panorama completo de opciones de conversión más allá de la línea de comandos
• ChatGPT a Word: el flujo de trabajo Markdown para documentos generados por IA
• Markdown a PDF: cuando el entregable es un PDF
• Problemas comunes de conversión de Markdown: soluciones para tablas rotas, problemas de codificación y desajustes de formato

Conclusión

Pandoc sigue siendo la respuesta correcta a «convertir Markdown a Word por línea de comandos»: un comando para un archivo suelto, un script corto para una carpeta, --reference-doc para el estilo corporativo. Nuestras pruebas mostraron que su soporte de matemáticas es mejor que su reputación: el LaTeX estándar se convierte en ecuaciones de Word reales y editables.

Su carencia genuina es visual: los diagramas Mermaid llegan como código fuente salvo que acople una cadena de filtros basada en Node. Así que elija según el flujo de trabajo. ¿Pipeline recurrente con documentos de texto plano? Automatícelo con pandoc. ¿Un documento con diagramas y fecha de entrega? Conviértalo en el navegador y mantenga intactas las ecuaciones y los diagramas de flujo.

Referencias

• Pandoc User's Guide — manual oficial: lectores, writers, --reference-doc, manejo de matemáticas
• Installing pandoc — instaladores oficiales para todas las plataformas
• mermaid-filter — filtro comunitario de pandoc para renderizar diagramas Mermaid
• pandoc/actions — GitHub Actions oficiales para pandoc en CI