Convertir documentos de Word a Markdown: Una guía completa

Convertir documentos Word a Markdown es una tarea muy común para escritores técnicos, desarrolladores y creadores de contenido que desean mover su contenido a plataformas que usan Markdown (como GitHub, GitLab, generadores de sitios estáticos como Hugo).

Esta guía cubre varios enfoques y herramientas para lograr esta conversión de manera efectiva.

¿Por qué convertir Word a Markdown?

Markdown ofrece varias ventajas sobre los documentos Word:

• Amigable para control de versiones: El formato de texto plano funciona bien con Git
• Independiente de la plataforma: Leible en cualquier sistema sin software especial
• Resistente al futuro: Formato de texto simple que no se volverá obsoleto
• Listo para la web: Fácil de convertir a HTML para sitios web y blogs
• Liviano: Tamaños de archivo mucho más pequeños
• Amigable para automatización: Fácil de procesar mediante programación

Lo que Pandoc preserva:

• Encabezados (convertidos a #, ##, ###, etc.)
• Negrita y cursiva
• Listas (punteadas y numeradas)
• Enlaces y referencias
• Tablas (convertidas a tablas de Markdown o HTML)
• Bloques de código y código en línea
• Imágenes (con la opción --extract-media)
• Notas al pie

Método 1: Usando Pandoc (Recomendado)

Pandoc es un convertidor universal de documentos que destaca al convertir entre diferentes formatos de marcado. Es la herramienta más confiable para convertir documentos Word a Markdown.

Instalando Pandoc

En Ubuntu/Debian:

sudo apt update
sudo apt install pandoc

En macOS:

# Usando Homebrew
brew install pandoc

# O descargue desde el sitio web oficial
# https://pandoc.org/installing.html

En Windows:

# Usando Chocolatey
choco install pandoc

# O descargue el instalador desde:
# https://github.com/jgm/pandoc/releases

Verificar la instalación:

pandoc --version

Convertir con Pandoc

Para archivos DOCX (formato moderno de Word):

pandoc document.docx -o document.md

Para archivos DOC antiguos: Pandoc no puede leer directamente archivos .doc. Debe convertirlos primero a .docx usando LibreOffice:

# Primero convertir DOC a DOCX
libreoffice --headless --convert-to docx document.doc

# Luego convertir DOCX a Markdown
pandoc document.docx -o document.md

Opciones avanzadas de Pandoc:

# Convertir con una variante específica de Markdown
pandoc document.docx -t gfm -o document.md  # Markdown con sabor a GitHub

# Extraer imágenes a una carpeta
pandoc document.docx --extract-media=./images -o document.md

# Preservar más formato
pandoc document.docx -t markdown+pipe_tables+raw_html -o document.md

# Convertir con una plantilla personalizada
pandoc document.docx --template=custom.template -o document.md

Método 2: Usando LibreOffice + Pandoc (Para archivos DOC)

Cuando se trata de archivos .doc antiguos, este proceso en dos pasos funciona mejor:

Instalando LibreOffice

En Ubuntu/Debian:

sudo apt update
sudo apt install libreoffice

En macOS:

brew install --cask libreoffice

En Windows: Descargue desde el sitio web de LibreOffice

Proceso de conversión:

# Paso 1: Convertir DOC a DOCX
libreoffice --headless --convert-to docx document.doc

# Paso 2: Convertir DOCX a Markdown con Pandoc
pandoc document.docx -o document.md

# Limpiar el archivo intermedio (opcional)
rm document.docx

Script de conversión por lotes con pandoc:

Cree un script para convertir varios archivos:

#!/bin/bash
# convert-docs.sh

for file in *.doc; do
    if [ -f "$file" ]; then
        echo "Convirtiendo $file..."
        
        # Convertir DOC a DOCX
        libreoffice --headless --convert-to docx "$file"
        
        # Obtener nombre de archivo sin extensión
        basename=$(basename "$file" .doc)
        
        # Convertir DOCX a Markdown
        pandoc "${basename}.docx" -o "${basename}.md"
        
        # Limpiar el archivo intermedio DOCX
        rm "${basename}.docx"
        
        echo "✓ Creado ${basename}.md"
    fi
done

Hágalo ejecutable y ejecute:

chmod +x convert-docs.sh
./convert-docs.sh

Método 3: Usando convertidores en línea (Rápido y fácil)

Para conversiones ocasionales, las herramientas en línea pueden ser convenientes:

Convertidores en línea populares:

• Pandoc Try: https://pandoc.org/try/
• Word to Markdown Converter: https://word2md.com/
• Dillinger: https://dillinger.io/ (tiene función de importación)

Ventajas y desventajas:

• Ventajas: No se requiere instalación, funciona en cualquier dispositivo
• Desventajas: Preocupaciones de privacidad, límites de tamaño de archivo, menos control sobre la salida

Método 4: Usando la exportación integrada de Word (Limitado)

Las versiones modernas de Microsoft Word pueden exportar a Markdown básico:

1. Abra su documento en Word
2. Vaya a Archivo → Exportar → Cambiar tipo de archivo
3. Seleccione Página web filtrada (*.html)
4. Use un convertidor de HTML a Markdown como Pandoc:

pandoc document.html -o document.md

Nota: Este método suele producir resultados inferiores en comparación con la conversión directa de DOCX.

Método 5: Soluciones de programación

Python con python-docx y markdownify:

#!/usr/bin/env python3
import sys
from docx import Document
from markdownify import markdownify

def docx_to_markdown(docx_path, md_path):
    # Leer el archivo docx
    doc = Document(docx_path)
    
    # Extraer texto (conversión básica)
    full_text = []
    for paragraph in doc.paragraphs:
        full_text.append(paragraph.text)
    
    # Convertir a markdown (básico)
    markdown_content = '\n\n'.join(full_text)
    
    # Escribir en archivo
    with open(md_path, 'w', encoding='utf-8') as f:
        f.write(markdown_content)

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print("Uso: python docx_to_md.py input.docx output.md")
        sys.exit(1)
    
    docx_to_markdown(sys.argv[1], sys.argv[2])
    print(f"Convertido {sys.argv[1]} a {sys.argv[2]}")

Instale las dependencias:

pip install python-docx markdownify

Nota: Esta es una implementación básica. Pandoc producirá mejores resultados para documentos complejos.

Manejo de problemas comunes

1. Tablas complejas

# Use el formato de tablas con tuberías para mejor compatibilidad
pandoc document.docx -t markdown+pipe_tables -o document.md

2. Imágenes que no se convierten

# Extraer imágenes a una carpeta separada
pandoc document.docx --extract-media=./images -o document.md

3. Pérdida de formato

# Preservar más HTML para formato complejo
pandoc document.docx -t markdown+raw_html -o document.md

4. Problemas de codificación de caracteres

# Especificar codificación UTF-8
pandoc document.docx -t markdown -o document.md --from=docx --to=markdown

Buenas prácticas

1. Preparación antes de la conversión

• Limpie su documento de Word antes de la conversión
• Use estilos de encabezado consistentes (Encabezado 1, Encabezado 2, etc.)
• Evite el formato complejo que no se traduzca bien a Markdown
• Use el formato de lista integrado de Word en lugar de viñetas manuales

2. Limpieza después de la conversión

• Revise la salida para problemas de formato
• Corrija el formato de tablas si es necesario
• Ajuste las rutas de imágenes y el texto alternativo
• Limpie los saltos de línea o problemas de espaciado adicionales

3. Consejos de automatización

# Cree un alias para conversiones comunes
echo 'alias doc2md="pandoc --from=docx --to=markdown"' >> ~/.bashrc

# Función para conversiones por lotes
doc2md_batch() {
    for file in *.docx; do
        pandoc "$file" -o "${file%.docx}.md"
    done
}

Comparación de métodos

Pequeña resumen

Para la mayoría de los usuarios, Pandoc es la solución recomendada para convertir documentos Word a Markdown. Proporciona el mejor equilibrio entre calidad, características y confiabilidad. Para archivos .doc antiguos, la combinación de LibreOffice + Pandoc funciona excelente.

La clave para una conversión exitosa es:

1. Preparar su documento de Word con formato consistente
2. Elegir la herramienta adecuada para sus necesidades específicas
3. Revisar y limpiar la salida
4. Automatizar el proceso si está haciendo conversiones regulares

Con estas herramientas y técnicas, puede convertir eficientemente sus documentos Word al formato Markdown mientras preserva la mayor parte del formato y estructura original.

Comandos de referencia rápida

# Conversión básica (DOCX a Markdown)
pandoc document.docx -o document.md

# DOC a Markdown (dos pasos)
libreoffice --headless --convert-to docx document.doc
pandoc document.docx -o document.md

# Markdown con sabor a GitHub
pandoc document.docx -t gfm -o document.md

# Extraer imágenes
pandoc document.docx --extract-media=./images -o document.md

# Convertir por lotes todos los archivos DOCX
for file in *.docx; do pandoc "$file" -o "${file%.docx}.md"; done

Enlaces útiles

• https://github.com/jgm/pandoc/releases/
• Hoja de referencia de Markdown
• Hoja de referencia de Python
• Hoja de referencia de Hugo
• Convertir contenido HTML a Markdown usando LLM y Ollama
• Añadir marcado de datos estructurados a Hugo
• Rendimiento de AWS Lambda: JavaScript vs Python vs Golang