Convertir DOCX a Markdown con Pandoc: guía completa

Convertir DOCX a Markdown con Pandoc: la guía completa

Pasar un documento Word a Markdown es uno de esos workflows que parecen triviales hasta que la primera tabla compleja, una imagen embebida o un footnote rompen la conversión. Pandoc es la herramienta canónica — universal, gratis, scriptable — pero requiere conocer sus flags para obtener resultado profesional.

Instalación

# macOS
brew install pandoc

# Linux Debian/Ubuntu
sudo apt install pandoc

# Windows: descarga instalador desde pandoc.org/installing.html
# o con winget:
winget install --id JohnMacFarlane.Pandoc

Verifica con pandoc --version (debe ser ≥3.0 para soporte completo de DOCX moderno).

Conversión básica

# DOCX → Markdown (variante GitHub Flavored Markdown)
pandoc -f docx -t gfm documento.docx -o documento.md

# Con extracción de imágenes a una carpeta
pandoc -f docx -t gfm documento.docx -o documento.md --extract-media=./imagenes

Esto descomprime el DOCX (que es un ZIP de XML), parsea el XML de OpenXML y emite Markdown equivalente. Las imágenes embebidas en el DOCX se extraen a ./imagenes/media/ con nombres como image1.png.

Variantes de Markdown — cuál elegir

Pandoc soporta varios "dialectos" de Markdown:

Para documentación que vivirá en GitHub: gfm. Para libros, papers o ebooks: markdown (con extensiones). Para máxima portabilidad: commonmark.

Tablas — el caso difícil

Las tablas son donde la conversión más se rompe. Word soporta tablas con celdas combinadas, alineaciones complejas y formato heterogéneo dentro de cada celda — Markdown solo soporta tablas simples.

# Habilitar conversión de tablas (sin esto, las omite o las trata como párrafos)
pandoc -f docx -t gfm documento.docx -o documento.md \
  --wrap=none

# Si las tablas tienen celdas combinadas, considera salida HTML para preservarlas
pandoc -f docx -t html documento.docx -o documento.html

Para tablas complejas, una alternativa es exportar la tabla a CSV (DOCX a CSV), procesarla aparte, y enlazar al CSV desde el Markdown.

Footnotes y referencias

Word usa footnotes nativas, Markdown estándar (CommonMark/gfm) no las soporta. La extensión markdown de Pandoc sí:

# Preservar footnotes
pandoc -f docx -t markdown documento.docx -o documento.md

Las footnotes se convierten a sintaxis [^1] con definiciones al final del documento.

Para referencias cruzadas (citas, bibliografía), Pandoc soporta el filtro pandoc-citeproc y archivos .bib:

pandoc -f docx -t markdown documento.docx \
  --citeproc \
  --bibliography=referencias.bib \
  -o documento.md

Estilos custom de Word — perdidos por defecto

Word permite estilos personalizados (ej. "Mi Estilo de Cita Empresarial"). Markdown no tiene equivalente. Por defecto Pandoc los descarta y aplica el estilo de párrafo más cercano.

Para preservar info de estilo via clases CSS-like (útil si después renderizas con un theme que las reconoce):

pandoc -f docx+styles -t markdown documento.docx -o documento.md

Esto añade {custom-style="MiEstilo"} después de cada bloque, que Pandoc puede convertir de vuelta a HTML/PDF preservando el estilo.

Batch — cientos de DOCX a la vez

# Linux/macOS — procesa todos los DOCX del directorio
for f in *.docx; do
  pandoc -f docx -t gfm "$f" -o "${f%.docx}.md" --extract-media=./media
done

# Paralelo (más rápido en máquinas multi-core)
ls *.docx | xargs -P $(nproc) -I {} \
  pandoc -f docx -t gfm "{}" -o "{}.md" --extract-media=./media

# Windows PowerShell
Get-ChildItem -Filter *.docx | ForEach-Object {
  pandoc -f docx -t gfm $_.Name -o ($_.BaseName + ".md") --extract-media=./media
}

Para repositorios donde la documentación entera está en DOCX, este es el primer paso para migrar a un static site generator (Hugo, Jekyll, MkDocs).

Limpieza típica post-conversión

Pandoc deja algunos artefactos que conviene limpiar después:

• Líneas en blanco múltiples entre párrafos: sed -i ':a;N;$!ba;s/\n\n\n*/\n\n/g' documento.md
• Anchors auto-generados de headings tipo [H1 Title]{#h-1-title}: filtrar con sed -E 's/\{#[a-z0-9-]+\}//g'
• Imágenes con tamaños inline: Pandoc añade {width="123" height="456"} — útil si lo respetas, ruido si no

Workflow completo: documentación legacy → MkDocs

# 1. Convertir todos los DOCX a Markdown con extracción de media
mkdir -p docs/media
for f in legacy/*.docx; do
  base=$(basename "$f" .docx)
  pandoc -f docx -t gfm "$f" -o "docs/${base}.md" \
    --extract-media=docs/media \
    --wrap=none
done

# 2. Estructura inicial de MkDocs
echo "site_name: Documentación" > mkdocs.yml
echo "nav:" >> mkdocs.yml
for f in docs/*.md; do
  base=$(basename "$f" .md)
  title=$(head -1 "$f" | sed 's/^#\s*//')
  echo "  - $title: $(basename $f)" >> mkdocs.yml
done

# 3. Servir local para revisar
pip install mkdocs-material
mkdocs serve

En 5 minutos tienes un site navegable de toda la documentación legacy de la empresa.

Cuándo NO usar Pandoc

• DOCX con muchas tablas complejas — la pérdida de fidelidad es alta. Mejor convertir a HTML preservando la estructura.
• DOCX con seguimiento de cambios activos — Pandoc respeta los cambios aceptados pero las anotaciones de revisión se pierden. Acepta primero todos los cambios en Word.
• DOCX protegido con contraseña o DRM — Pandoc no descifra. Quita la protección en Word/LibreOffice primero.
• Documentos con macros (.docm) — Pandoc convierte el contenido pero pierde las macros (Markdown no soporta scripting).

Conversiones relacionadas

• DOCX a PDF — para entrega final con formato preservado
• DOCX a HTML — para web manteniendo estilos
• DOCX a TXT — solo el texto, descarta formato
• DOCX a EPUB — para distribuir como ebook
• PDF a DOCX — operación inversa si recibes PDF
• HTML a Markdown — para convertir desde web en lugar de Word