MarkItDown - Conversión de Archivos a Markdown

¿Qué hace MarkItDown - Conversión de Archivos a Markdown?

Descripción General

MarkItDown es una herramienta de Python desarrollada por Microsoft para convertir varios formatos de archivo a Markdown. Es particularmente útil para convertir documentos en un formato de texto amigable para LLMs, ya que Markdown es eficiente en tokens y bien comprendido por los modelos de lenguaje modernos.

Beneficios Clave:

• Convierte documentos a Markdown limpio y estructurado
• Formato eficiente en tokens para el procesamiento con LLMs
• Soporta más de 15 formatos de archivo
• Descripciones de imágenes mejoradas por IA (opcional)
• OCR para imágenes y documentos escaneados
• Transcripción de voz para archivos de audio

Mejora Visual con Esquemas Científicos

Al crear documentos con esta habilidad, considere siempre agregar diagramas y esquemas científicos para mejorar la comunicación visual.

Si su documento aún no contiene esquemas o diagramas:

• Use la habilidad esquemas-científicos para generar diagramas de calidad de publicación impulsados por IA
• Simplemente describa el diagrama deseado en lenguaje natural
• Nano Banana Pro generará, revisará y refinará automáticamente el esquema

Para documentos nuevos: Los esquemas científicos deben generarse por defecto para representar visualmente conceptos clave, flujos de trabajo, arquitecturas o relaciones descritas en el texto.

Cómo generar esquemas:

python scripts/generate_schematic.py "su descripción del diagrama" -o figures/output.png

La IA automáticamente:

• Creará imágenes de calidad de publicación con formato adecuado
• Revisará y refinará a través de múltiples iteraciones
• Garantizará accesibilidad (compatible con daltonismo, alto contraste)
• Guardará los resultados en el directorio figures/

Cuándo agregar esquemas:

• Diagramas de flujo de trabajo de conversión de documentos
• Ilustraciones de arquitectura de formatos de archivo
• Diagramas de tuberías de procesamiento OCR
• Visualizaciones de flujo de trabajo de integración
• Diagramas de arquitectura de sistemas
• Diagramas de flujo de datos
• Cualquier concepto complejo que se beneficie de la visualización

Para obtener una guía detallada sobre la creación de esquemas, consulte la documentación de la habilidad esquemas-científicos.

---

Formatos Soportados

Formato	Descripción	Notas
PDF	Formato de Documento Portátil	Extracción de texto completa
DOCX	Microsoft Word	Tablas, formato preservado
PPTX	PowerPoint	Diapositivas con notas
XLSX	Hojas de cálculo de Excel	Tablas y datos
Imágenes	JPEG, PNG, GIF, WebP	Metadatos EXIF + OCR
Audio	WAV, MP3	Metadatos + transcripción
HTML	Páginas web	Conversión limpia
CSV	Valores separados por comas	Formato de tabla
JSON	Datos JSON	Representación estructurada
XML	Documentos XML	Formato estructurado
ZIP	Archivos comprimidos	Itera sobre contenidos
EPUB	Libros electrónicos	Extracción de texto completa
YouTube	URLs de video	Obtener transcripciones

Inicio Rápido

Instalación

# Instalar con todas las características
pip install 'markitdown[all]'

# O desde la fuente
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Uso en Línea de Comandos

# Conversión básica
markitdown document.pdf > output.md

# Especificar archivo de salida
markitdown document.pdf -o output.md

# Tubería de contenido
cat document.pdf | markitdown > output.md

# Habilitar plugins
markitdown --list-plugins  # Listar plugins disponibles
markitdown --use-plugins document.pdf -o output.md

API de Python

from markitdown import MarkItDown

# Uso básico
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# Convertir desde un flujo
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    print(result.text_content)

Características Avanzadas

1. Descripciones de Imágenes Mejoradas por IA

Use LLMs a través de OpenRouter para generar descripciones detalladas de imágenes (para archivos PPTX e imágenes):

from markitdown import MarkItDown
from openai import OpenAI

# Inicializar cliente OpenRouter (API compatible con OpenAI)
client = OpenAI(
    api_key="su-clave-api-openrouter",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # recomendado para visión científica
    llm_prompt="Describa esta imagen en detalle para documentación científica"
)

result = md.convert("presentation.pptx")
print(result.text_content)

2. Azure Document Intelligence

Para conversión mejorada de PDF con Microsoft Document Intelligence:

# Línea de comandos
markitdown document.pdf -o output.md -d -e "<endpoint_de_document_intelligence>"

# API de Python
from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<endpoint_de_document_intelligence>")
result = md.convert("complex_document.pdf")
print(result.text_content)

3. Sistema de Plugins

MarkItDown admite plugins de terceros para ampliar la funcionalidad:

# Listar plugins instalados
markitdown --list-plugins

# Habilitar plugins
markitdown --use-plugins file.pdf -o output.md

Encuentre plugins en GitHub con el hashtag: #markitdown-plugin

Dependencias Opcionales

Controle qué formatos de archivo soporta:

# Instalar formatos específicos
pip install 'markitdown[pdf, docx, pptx]'

# Todas las opciones disponibles:
# [all]                  - Todas las dependencias opcionales
# [pptx]                 - Archivos de PowerPoint
# [docx]                 - Documentos de Word
# [xlsx]                 - Hojas de cálculo de Excel
# [xls]                  - Archivos de Excel antiguos
# [pdf]                  - Documentos PDF
# [outlook]              - Mensajes de Outlook
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - Transcripción de WAV y MP3
# [youtube-transcription] - Transcripción de videos de YouTube

Casos de Uso Comunes

1. Convertir Artículos Científicos a Markdown

from markitdown import MarkItDown

md = MarkItDown()

# Convertir PDF de artículo
result = md.convert("research_paper.pdf")
with open("paper.md", "w") as f:
    f.write(result.text_content)

2. Extraer Datos de Excel para Análisis

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.xlsx")

# El resultado estará en formato de tabla Markdown
print(result.text_content)

3. Procesar Múltiples Documentos

from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# Procesar todos los PDFs en un directorio
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    result = md.convert(str(pdf_file))
    output_file = output_dir / f"{pdf_file.stem}.md"
    output_file.write_text(result.text_content)
    print(f"Convertido: {pdf_file.name}")

4. Convertir PowerPoint con Descripciones de IA

from markitdown import MarkItDown
from openai import OpenAI

# Usar OpenRouter para acceder a múltiples modelos de IA
client = OpenAI(
    api_key="su-clave-api-openrouter",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # recomendado para presentaciones
    llm_prompt="Describa esta imagen de diapositiva en detalle, enfocándose en elementos visuales clave y datos"
)

result = md.convert("presentation.pptx")
with open("presentation.md", "w") as f:
    f.write(result.text_content)

5. Conversión por Lotes con Diferentes Formatos

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Archivos a convertir
files = [
    "document.pdf",
    "spreadsheet.xlsx",
    "presentation.pptx",
    "notes.docx"
]

for file in files:
    try:
        result = md.convert(file)
        output = Path(file).stem + ".md"
        with open(output, "w") as f:
            f.write(result.text_content)
        print(f"✓ Convertido {file}")
    except Exception as e:
        print(f"✗ Error al convertir {file}: {e}")

6. Extraer Transcripción de Video de YouTube

from markitdown import MarkItDown

md = MarkItDown()

# Convertir video de YouTube a transcripción
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

Uso con Docker

# Construir imagen
docker build -t markitdown:latest .

# Ejecutar conversión
docker run --rm -i markitdown:latest < ~/document.pdf > output.md

Mejores Prácticas

1. Elegir el Método de Conversión Correcto

• Documentos simples: Usar MarkItDown() básico
• PDFs complejos: Usar Azure Document Intelligence
• Contenido visual: Habilitar descripciones de imágenes con IA
• Documentos escaneados: Asegurar que las dependencias de OCR estén instaladas

2. Manejar Errores de Forma Elegante

from markitdown import MarkItDown

md = MarkItDown()

try:
    result = md.convert("document.pdf")
    print(result.text_content)
except FileNotFoundError:
    print("Archivo no encontrado")
except Exception as e:
    print(f"Error de conversión: {e}")

3. Procesar Archivos Grandes de Manera Eficiente

from markitdown import MarkItDown

md = MarkItDown()

# Para archivos grandes, usar flujo
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # Procesar en fragmentos o guardar directamente
    with open("output.md", "w") as out:
        out.write(result.text_content)

4. Optimizar para Eficiencia de Tokens

La salida Markdown ya es eficiente en tokens, pero puede:

• Eliminar espacios en blanco excesivos
• Consolidar secciones similares
• Eliminar metadatos si no son necesarios

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("document.pdf")

# Limpiar espacios en blanco adicionales
clean_text = re.sub(r'\n{3,}', '\n\n', result.text_content)
clean_text = clean_text.strip()

print(clean_text)

Integración con Flujos de Trabajo Científicos

Convertir Literatura para Revisión

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# Convertir todos los artículos en la carpeta de literatura
papers_dir = Path("literature/pdfs")
output_dir = Path("literature/markdown")
output_dir.mkdir(exist_ok=True)

for paper in papers_dir.glob("*.pdf"):
    result = md.convert(str(paper))
    
    # Guardar con metadatos
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**Fuente**: {paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# Para conversión mejorada con IA que incluya figuras
from openai import OpenAI

client = OpenAI(
    api_key="su-clave-api-openrouter",
    base_url="https://openrouter.ai/api/v1"
)

md_ai = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",
    llm_prompt="Describa figuras científicas con precisión técnica"
)

Extraer Tablas para Análisis

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("data_tables.xlsx")

# Las tablas Markdown se pueden analizar o usar directamente
print(result.text_content)

Solución de Problemas

Problemas Comunes

1. Dependencias faltantes: Instalar paquetes de características específicas

   pip install 'markitdown[pdf]'  # Para soporte de PDF
   

2. Errores de archivos binarios: Asegurar que los archivos se abran en modo binario

   with open("file.pdf", "rb") as f:  # Note el "rb"
       result = md.convert_stream(f, file_extension=".pdf")
   

3. OCR no funciona: Instalar tesseract

   # macOS
   brew install tesseract
   
   # Ubuntu
   sudo apt-get install tesseract-ocr
   

Consideraciones de Rendimiento

• Archivos PDF: Los PDFs grandes pueden llevar tiempo; considere rangos de páginas si son compatibles
• OCR de imágenes: El procesamiento OCR requiere mucha CPU
• Transcripción de audio: Requiere recursos computacionales adicionales
• Descripciones de imágenes con IA: Requiere llamadas a API (pueden aplicarse costos)

Próximos Pasos

• Consulte references/api_reference.md para la documentación completa de la API
• Revise references/file_formats.md para detalles específicos de formato
• Examine scripts/batch_convert.py para ejemplos de automatización
• Explore scripts/convert_with_ai.py para conversiones mejoradas con IA

Recursos

• MarkItDown GitHub: https://github.com/microsoft/markitdown
• PyPI: https://pypi.org/project/markitdown/
• OpenRouter: https://openrouter.ai (para conversiones mejoradas con IA)
• Claves de API de OpenRouter: https://openrouter.ai/keys
• Modelos de OpenRouter: https://openrouter.ai/models
• Servidor MCP: markitdown-mcp (para integración con Claude Desktop)
• Desarrollo de Plugins: Consulte packages/markitdown-sample-plugin