MarkItDown - Conversão de Arquivos para Markdown
Visão Geral
MarkItDown é uma ferramenta Python desenvolvida pela Microsoft para converter vários formatos de arquivo para Markdown. É particularmente útil para converter documentos em formato de texto amigável para LLMs, já que Markdown é eficiente em tokens e bem compreendido por modelos de linguagem modernos.
Principais Benefícios:
- Converta documentos para Markdown limpo e estruturado
- Formato eficiente em tokens para processamento com LLMs
- Suporta mais de 15 formatos de arquivo
- Descrições de imagens aprimoradas por IA (opcional)
- OCR para imagens e documentos digitalizados
- Transcrição de fala para arquivos de áudio
Aprimoramento Visual com Esquemas Científicos
Ao criar documentos com esta skill, sempre considere adicionar diagramas e esquemas científicos para melhorar a comunicação visual.
Se o seu documento ainda não contiver esquemas ou diagramas:
- Use a skill scientific-schematics para gerar diagramas de qualidade prontos para publicação
- Simplesmente descreva o diagrama desejado em linguagem natural
- O Nano Banana Pro irá automaticamente gerar, revisar e refinar o esquema
Para novos documentos: Esquemas científicos devem ser gerados por padrão para representar visualmente conceitos-chave, fluxos de trabalho, arquiteturas ou relacionamentos descritos no texto.
Como gerar esquemas:
python scripts/generate_schematic.py "sua descrição do diagrama" -o figures/output.png
A IA irá automaticamente:
- Criar imagens de qualidade prontas para publicação com formatação adequada
- Revisar e refinar através de múltiplas iterações
- Garantir acessibilidade (compatível com daltonismo, alto contraste)
- Salvar as saídas no diretório figures/
Quando adicionar esquemas:
- Diagramas de fluxo de trabalho de conversão de documentos
- Ilustrações de arquitetura de formatos de arquivo
- Diagramas de pipeline de processamento OCR
- Visualizações de fluxo de trabalho de integração
- Diagramas de arquitetura de sistema
- Diagramas de fluxo de dados
- Qualquer conceito complexo que se beneficie de visualização
Para orientação detalhada sobre criação de esquemas, consulte a documentação da skill scientific-schematics.
Formatos Suportados
| Formato | Descrição | Notas |
|---|---|---|
| Portable Document Format | Extração completa de texto | |
| DOCX | Microsoft Word | Tabelas, formatação preservada |
| PPTX | PowerPoint | Slides com anotações |
| XLSX | Planilhas Excel | Tabelas e dados |
| Imagens | JPEG, PNG, GIF, WebP | Metadados EXIF + OCR |
| Áudio | WAV, MP3 | Metadados + transcrição |
| HTML | Páginas web | Conversão limpa |
| CSV | Valores separados por vírgula | Formato de tabela |
| JSON | Dados JSON | Representação estruturada |
| XML | Documentos XML | Formato estruturado |
| ZIP | Arquivos compactados | Itera sobre os conteúdos |
| EPUB | E-books | Extração completa de texto |
| YouTube | URLs de vídeo | Buscar transcrições |
Início Rápido
Instalação
# Instalar com todos os recursos
pip install 'markitdown[all]'
# Ou a partir do código-fonte
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
Uso via Linha de Comando
# Conversão básica
markitdown document.pdf > output.md
# Especificar arquivo de saída
markitdown document.pdf -o output.md
# Usar pipe
cat document.pdf | markitdown > output.md
# Habilitar plugins
markitdown --list-plugins # Listar plugins disponíveis
markitdown --use-plugins document.pdf -o output.md
API Python
from markitdown import MarkItDown
# Uso básico
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)
# Converter a partir de um stream
with open("document.pdf", "rb") as f:
result = md.convert_stream(f, file_extension=".pdf")
print(result.text_content)
Recursos Avançados
1. Descrições de Imagens Aprimoradas por IA
Use LLMs via OpenRouter para gerar descrições detalhadas de imagens (para arquivos PPTX e imagens):
from markitdown import MarkItDown
from openai import OpenAI
# Inicializar cliente OpenRouter (API compatível com OpenAI)
client = OpenAI(
api_key="sua-chave-da-api-openrouter",
base_url="https://openrouter.ai/api/v1"
)
md = MarkItDown(
llm_client=client,
llm_model="anthropic/claude-sonnet-4.5", # recomendado para visão científica
llm_prompt="Descreva esta imagem em detalhes para documentação científica"
)
result = md.convert("apresentacao.pptx")
print(result.text_content)
2. Azure Document Intelligence
Para conversão aprimorada de PDF com Microsoft Document Intelligence:
# Linha de comando
markitdown document.pdf -o output.md -d -e "<endpoint_do_document_intelligence>"
# API Python
from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<endpoint_do_document_intelligence>")
result = md.convert("documento_complexo.pdf")
print(result.text_content)
3. Sistema de Plugins
MarkItDown suporta plugins de terceiros para estender a funcionalidade:
# Listar plugins instalados
markitdown --list-plugins
# Habilitar plugins
markitdown --use-plugins file.pdf -o output.md
Encontre plugins no GitHub com a hashtag: #markitdown-plugin
Dependências Opcionais
Controle quais formatos de arquivo você suporta:
# Instalar formatos específicos
pip install 'markitdown[pdf, docx, pptx]'
# Todas as opções disponíveis:
# [all] - Todas as dependências opcionais
# [pptx] - Arquivos PowerPoint
# [docx] - Documentos Word
# [xlsx] - Planilhas Excel
# [xls] - Arquivos Excel antigos
# [pdf] - Documentos PDF
# [outlook] - Mensagens do Outlook
# [az-doc-intel] - Azure Document Intelligence
# [audio-transcription] - Transcrição de WAV e MP3
# [youtube-transcription] - Transcrição de vídeos do YouTube
Casos de Uso Comuns
1. Converter Artigos Científicos para Markdown
from markitdown import MarkItDown
md = MarkItDown()
# Converter artigo em PDF
result = md.convert("artigo_pesquisa.pdf")
with open("artigo.md", "w") as f:
f.write(result.text_content)
2. Extrair Dados do Excel para Análise
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("dados.xlsx")
# O resultado estará no formato de tabela Markdown
print(result.text_content)
3. Processar Múltiplos Documentos
from markitdown import MarkItDown
import os
from pathlib import Path
md = MarkItDown()
# Processar todos os PDFs em um diretório
dir_pdf = Path("artigos/")
dir_saida = Path("saida_markdown/")
dir_saida.mkdir(exist_ok=True)
for arquivo_pdf in dir_pdf.glob("*.pdf"):
result = md.convert(str(arquivo_pdf))
arquivo_saida = dir_saida / f"{arquivo_pdf.stem}.md"
arquivo_saida.write_text(result.text_content)
print(f"Convertido: {arquivo_pdf.name}")
4. Converter PowerPoint com Descrições de IA
from markitdown import MarkItDown
from openai import OpenAI
# Use OpenRouter para acesso a múltiplos modelos de IA
client = OpenAI(
api_key="sua-chave-da-api-openrouter",
base_url="https://openrouter.ai/api/v1"
)
md = MarkItDown(
llm_client=client,
llm_model="anthropic/claude-sonnet-4.5", # recomendado para apresentações
llm_prompt="Descreva esta imagem de slide em detalhes, focando nos elementos visuais e dados principais"
)
result = md.convert("apresentacao.pptx")
with open("apresentacao.md", "w") as f:
f.write(result.text_content)
5. Conversão em Lote com Diferentes Formatos
from markitdown import MarkItDown
from pathlib import Path
md = MarkItDown()
# Arquivos para converter
arquivos = [
"documento.pdf",
"planilha.xlsx",
"apresentacao.pptx",
"anotacoes.docx"
]
for arquivo in arquivos:
try:
result = md.convert(arquivo)
saida = Path(arquivo).stem + ".md"
with open(saida, "w") as f:
f.write(result.text_content)
print(f"✓ Convertido {arquivo}")
except Exception as e:
print(f"✗ Erro ao converter {arquivo}: {e}")
6. Extrair Transcrição de Vídeo do YouTube
from markitdown import MarkItDown
md = MarkItDown()
# Converter vídeo do YouTube para transcrição
result = md.convert("https://www.youtube.com/watch?v=ID_DO_VIDEO")
print(result.text_content)
Uso com Docker
# Construir imagem
docker build -t markitdown:latest .
# Executar conversão
docker run --rm -i markitdown:latest < ~/documento.pdf > output.md
Melhores Práticas
1. Escolha o Método de Conversão Adequado
- Documentos simples: Use
MarkItDown()básico - PDFs complexos: Use Azure Document Intelligence
- Conteúdo visual: Ative descrições de imagens com IA
- Documentos digitalizados: Certifique-se de que as dependências de OCR estão instaladas
2. Trate Erros com Elegância
from markitdown import MarkItDown
md = MarkItDown()
try:
result = md.convert("documento.pdf")
print(result.text_content)
except FileNotFoundError:
print("Arquivo não encontrado")
except Exception as e:
print(f"Erro de conversão: {e}")
3. Processe Arquivos Grandes com Eficiência
from markitdown import MarkItDown
md = MarkItDown()
# Para arquivos grandes, use streaming
with open("arquivo_grande.pdf", "rb") as f:
result = md.convert_stream(f, file_extension=".pdf")
# Processe em partes ou salve diretamente
with open("output.md", "w") as out:
out.write(result.text_content)
4. Otimize para Eficiência de Tokens
A saída Markdown já é eficiente em tokens, mas você pode:
- Remover espaços em branco excessivos
- Consolidar seções similares
- Remover metadados se não forem necessários
from markitdown import MarkItDown
import re
md = MarkItDown()
result = md.convert("documento.pdf")
# Limpar espaços em branco extras
texto_limpo = re.sub(r'\n{3,}', '\n\n', result.text_content)
texto_limpo = texto_limpo.strip()
print(texto_limpo)
Integração com Fluxos de Trabalho Científicos
Converter Literatura para Revisão
from markitdown import MarkItDown
from pathlib import Path
md = MarkItDown()
# Converter todos os artigos na pasta de literatura
dir_artigos = Path("literatura/pdfs")
dir_saida = Path("literatura/markdown")
dir_saida.mkdir(exist_ok=True)
for artigo in dir_artigos.glob("*.pdf"):
result = md.convert(str(artigo))
# Salvar com metadados
arquivo_saida = dir_saida / f"{artigo.stem}.md"
conteudo = f"# {artigo.stem}\n\n"
conteudo += f"**Fonte**: {artigo.name}\n\n"
conteudo += "---\n\n"
conteudo += result.text_content
arquivo_saida.write_text(conteudo)
# Para conversão aprimorada com IA incluindo figuras
from openai import OpenAI
client = OpenAI(
api_key="sua-chave-da-api-openrouter",
base_url="https://openrouter.ai/api/v1"
)
md_ia = MarkItDown(
llm_client=client,
llm_model="anthropic/claude-sonnet-4.5",
llm_prompt="Descreva figuras científicas com precisão técnica"
)
Extrair Tabelas para Análise
from markitdown import MarkItDown
import re
md = MarkItDown()
result = md.convert("tabelas_dados.xlsx")
# Tabelas Markdown podem ser analisadas ou usadas diretamente
print(result.text_content)
Solução de Problemas
Problemas Comuns
-
Dependências ausentes: Instale pacotes específicos do formato
pip install 'markitdown[pdf]' # Para suporte a PDF -
Erros de arquivo binário: Certifique-se de que os arquivos são abertos em modo binário
with open("arquivo.pdf", "rb") as f: # Observe o "rb" result = md.convert_stream(f, file_extension=".pdf") -
OCR não funciona: Instale o tesseract
# macOS brew install tesseract # Ubuntu sudo apt-get install tesseract-ocr
Considerações de Desempenho
- Arquivos PDF: PDFs grandes podem levar tempo; considere intervalos de páginas, se suportado
- OCR de imagens: O processamento OCR é intensivo em CPU
- Transcrição de áudio: Requer recursos computacionais adicionais
- Descrições de imagens com IA: Requer chamadas de API (custos podem ser aplicados)
Próximos Passos
- Veja
references/api_reference.mdpara documentação completa da API - Consulte
references/file_formats.mdpara detalhes específicos de cada formato - Revise
scripts/batch_convert.pypara exemplos de automação - Explore
scripts/convert_with_ai.pypara conversões aprimoradas com IA
Recursos
- MarkItDown GitHub: https://github.com/microsoft/markitdown
- PyPI: https://pypi.org/project/markitdown/
- OpenRouter: https://openrouter.ai (para conversões aprimoradas com IA)
- Chaves de API do OpenRouter: https://openrouter.ai/keys
- Modelos do OpenRouter: https://openrouter.ai/models
- Servidor MCP: markitdown-mcp (para integração com Claude Desktop)
- Desenvolvimento de Plugins: Veja
packages/markitdown-sample-plugin