Pandoc es la navaja suiza de la conversión de documentos. Soporta más de 40 formatos y su pipeline DOCX → Markdown es especialmente útil para escritores técnicos, documentación de software y blogs estáticos.
## Instalación
```bash
# Ubuntu / Debian
sudo apt install pandoc
# macOS
brew install pandoc
# Windows (winget)
winget install JohnMacFarlane.Pandoc
# Verificar versión
pandoc --version
```
## Conversión básica
```bash
# Salida Markdown estándar
pandoc documento.docx -o documento.md
# GitHub Flavored Markdown (tablas nativas, task lists)
pandoc documento.docx -t gfm -o documento.md
# CommonMark estricto
pandoc documento.docx -t commonmark -o documento.md
# Especificar formato de entrada explícitamente
pandoc -f docx -t gfm documento.docx -o documento.md
```
## Manejo de imágenes
Las imágenes embebidas en el DOCX se extraen a carpeta con `--extract-media`:
```bash
# Extraer imágenes junto al archivo Markdown
pandoc documento.docx -t gfm --extract-media=. -o documento.md
# Crea: ./media/image1.png, ./media/image2.jpeg …
# El MD resultante: 
# Personalizar directorio
pandoc documento.docx -t gfm --extract-media=assets/imgs -o documento.md
```
## Manejo de tablas
```bash
# Tablas pipe (compatibles con GitHub, Obsidian, Notion)
pandoc documento.docx -t gfm -o documento.md
# Tablas grid (soportan celdas multilínea)
pandoc documento.docx -t markdown+grid_tables -o documento.md
# Resultado típico (pipe tables):
# | Columna A | Columna B | Columna C |
# |-----------|-----------|-----------|
# | Valor 1 | Valor 2 | Valor 3 |
```
## Notas al pie
```bash
# Notas al pie estilo Markdown
pandoc documento.docx -t markdown+footnotes -o documento.md
# Genera: texto[^1] … [^1]: Contenido de la nota.
# Con GFM (estilo GitHub)
pandoc documento.docx -t gfm -o documento.md
```
## Opciones de formato recomendadas
```bash
# --wrap=none: sin saltos de línea automáticos (ideal para git diff)
pandoc documento.docx -t gfm --wrap=none -o documento.md
# ATX headings (# ## ###) en lugar de Setext (=== ---)
pandoc documento.docx -t markdown-setext_headings --wrap=none -o documento.md
# Combinación recomendada para documentación técnica
pandoc documento.docx \
-t gfm \
--wrap=none \
--extract-media=./imagenes \
-o documento.md
```
## Conversión masiva en Bash
```bash
#!/bin/bash
mkdir -p output/imagenes
for f in *.docx; do
nombre="${f%.docx}"
echo "-> Convirtiendo: $f"
pandoc "$f" \
-t gfm \
--wrap=none \
--extract-media="output/imagenes/${nombre}" \
-o "output/${nombre}.md"
done
total=$(ls output/*.md 2>/dev/null | wc -l)
echo "Conversion completa: $total archivos"
```
## Python con pypandoc
```python
# pip install pypandoc
import pypandoc
# Convertir y capturar resultado en string
contenido_md = pypandoc.convert_file('documento.docx', 'gfm')
print(contenido_md[:300])
# Guardar directamente a archivo
pypandoc.convert_file(
'documento.docx',
'gfm',
outputfile='documento.md',
extra_args=['--wrap=none', '--extract-media=./media'],
)
# Conversión masiva
from pathlib import Path
origen = Path('documentos_word')
destino = Path('markdown_output')
destino.mkdir(exist_ok=True)
for docx in sorted(origen.glob('*.docx')):
md_path = destino / docx.with_suffix('.md').name
pypandoc.convert_file(
str(docx),
'gfm',
outputfile=str(md_path),
extra_args=['--wrap=none'],
)
print(f'OK: {docx.name}')
print(f'Total: {len(list(destino.glob("*.md")))} archivos convertidos')
```
## Problemas comunes y soluciones
**Caracteres corruptos (ñ, tildes…):**
```bash
# Pandoc usa UTF-8 por defecto; recodificar si es necesario
iconv -f latin1 -t utf-8 documento.md > documento_utf8.md
```
**Estilos de Word personalizados no convertidos:**
```bash
# Los estilos "Código" o "Nota" de Word no se mapean automáticamente
# Solución: usar lua filter para mapear estilos a bloques Markdown
# pandoc documento.docx -t gfm --lua-filter=estilo-codigo.lua -o doc.md
```
**El DOCX tiene imágenes pero no se extraen:**
```bash
# Verificar integridad del DOCX (es un ZIP)
unzip -t documento.docx
# Extraer manualmente para inspeccionar
unzip documento.docx -d contenido_docx
ls contenido_docx/word/media/
```
## Verificar calidad de conversión
```bash
# Convertir de vuelta a DOCX para comparación visual
pandoc documento.md -o verificacion.docx
# Comparar texto plano (diff estructural)
pandoc documento.docx -t plain -o original.txt
pandoc documento.md -t plain -o convertido.txt
diff original.txt convertido.txt
```
Guía