MarkItDown: Convertendo Documentos para Markdown com Python | python.dev.br

Se você já tentou alimentar um LLM com dados de PDFs, planilhas Excel ou apresentações PowerPoint, sabe que o maior desafio não é a chamada à API — é extrair o conteúdo de forma limpa. O MarkItDown, biblioteca open-source da Microsoft, resolve exatamente esse problema: converte dezenas de formatos de arquivo em Markdown estruturado, pronto para uso com modelos de linguagem.

Com mais de 50 mil estrelas no GitHub em poucos meses, o MarkItDown se tornou uma das ferramentas mais populares do ecossistema Python em 2026. Neste artigo, vamos explorar como instalá-lo, converter diferentes tipos de documento, e integrá-lo em pipelines de IA reais.

Por que Markdown para LLMs?

Modelos como GPT-4o, Claude e Gemini “falam” Markdown nativamente. Quando você envia um documento em Markdown para um LLM, o modelo consegue entender a hierarquia de títulos, tabelas, listas e links sem precisar de parsing adicional.

O problema é que a maioria dos dados corporativos está em formatos binários — PDF, DOCX, XLSX, PPTX. Converter esses formatos para texto puro perde a estrutura. Converter para Markdown preserva a estrutura de forma que o LLM consegue interpretar.

É aí que o MarkItDown entra: ele pega um arquivo em qualquer formato suportado e gera Markdown limpo, com tabelas, cabeçalhos e formatação preservados.

Instalação

O MarkItDown está disponível no PyPI. Se você usa pip ou uv, a instalação é direta:

# Instalação básica
# pip install markitdown

# Com suporte a todos os formatos opcionais
# pip install "markitdown[all]"

# Com uv (recomendado)
# uv add "markitdown[all]"

O pacote [all] inclui dependências para PDF, áudio, imagens e outros formatos que precisam de bibliotecas extras.

Uso básico: convertendo arquivos

A API do MarkItDown é simples — um conversor e um método convert:

from markitdown import MarkItDown

conversor = MarkItDown()

# Converter um arquivo PDF
resultado = conversor.convert("relatorio-financeiro.pdf")
print(resultado.text_content)

O retorno é um objeto com o atributo text_content contendo o Markdown gerado. Vamos ver exemplos com diferentes formatos.

Convertendo documentos Word (DOCX)

resultado = conversor.convert("proposta-comercial.docx")
print(resultado.text_content)

Saída típica:

# Proposta Comercial — Projeto Alpha

## Escopo do Projeto

O projeto Alpha visa implementar um sistema de...

## Cronograma

| Fase | Início | Término | Responsável |
|------|--------|---------|-------------|
| Descoberta | 01/05/2026 | 15/05/2026 | Equipe A |
| Desenvolvimento | 16/05/2026 | 30/07/2026 | Equipe B |

Note como tabelas, títulos e formatação são preservados como Markdown válido.

Convertendo planilhas Excel (XLSX)

resultado = conversor.convert("vendas-q1-2026.xlsx")
print(resultado.text_content)

O MarkItDown converte cada aba da planilha em uma seção com tabelas Markdown. Isso é extremamente útil para análise de dados com LLMs — em vez de usar pandas para processar e depois explicar os dados, você pode enviar a planilha direto para o modelo.

Convertendo apresentações PowerPoint (PPTX)

resultado = conversor.convert("apresentacao-resultados.pptx")
print(resultado.text_content)

Cada slide vira uma seção, com textos, bullet points e notas do apresentador preservados. Imagens nos slides recebem descrições quando integrado com um modelo de visão.

Convertendo PDFs

resultado = conversor.convert("contrato-servicos.pdf")
print(resultado.text_content)

PDFs são o formato mais desafiador por causa da variedade de estruturas internas. O MarkItDown usa heurísticas para detectar títulos, parágrafos e tabelas, mas PDFs escaneados (imagens) precisam de OCR adicional.

Convertendo páginas HTML e URLs

Além de arquivos locais, o MarkItDown converte HTML e até busca URLs diretamente:

# HTML local
resultado = conversor.convert("pagina.html")

# URL remota
resultado = conversor.convert("https://python.dev.br/blog/")
print(resultado.text_content)

Isso é útil para web scraping onde você quer o conteúdo em Markdown limpo, sem precisar parsear HTML manualmente com BeautifulSoup.

Integração com LLMs para descrição de imagens

Uma funcionalidade que diferencia o MarkItDown é a integração com modelos de visão para descrever imagens automaticamente:

from openai import OpenAI

cliente = OpenAI()

conversor = MarkItDown(
    llm_client=cliente,
    llm_model="gpt-4o-mini",
)

# Converter imagem com descrição gerada por IA
resultado = conversor.convert("grafico-vendas.png")
print(resultado.text_content)
# Saída: "Gráfico de barras mostrando vendas mensais de janeiro a março de 2026..."

Quando o MarkItDown encontra uma imagem (seja um arquivo direto ou embutida em um PPTX/DOCX), ele envia para o modelo de visão e inclui a descrição no Markdown gerado. Para quem trabalha com processamento de imagens, essa integração elimina uma etapa manual.

Uso na linha de comando

O MarkItDown também funciona como ferramenta CLI, útil para automação com scripts:

# Converter arquivo único
markitdown relatorio.pdf > relatorio.md

# Converter com saída no terminal
markitdown apresentacao.pptx

Se você gosta de criar ferramentas de linha de comando, pode integrar o MarkItDown em seus próprios scripts facilmente.

Pipeline prático: RAG com documentos corporativos

Um caso de uso real é construir um sistema de Retrieval-Augmented Generation (RAG) que indexa documentos da empresa. Veja um pipeline simplificado:

from markitdown import MarkItDown
from pathlib import Path

conversor = MarkItDown()

def processar_documentos(pasta: str) -> list[dict]:
    """Converte todos os documentos de uma pasta para Markdown."""
    documentos = []
    formatos_suportados = {".pdf", ".docx", ".xlsx", ".pptx", ".html"}

    for arquivo in Path(pasta).rglob("*"):
        if arquivo.suffix.lower() in formatos_suportados:
            try:
                resultado = conversor.convert(str(arquivo))
                documentos.append({
                    "nome": arquivo.name,
                    "caminho": str(arquivo),
                    "conteudo": resultado.text_content,
                    "formato": arquivo.suffix,
                })
                print(f"Convertido: {arquivo.name}")
            except Exception as e:
                print(f"Erro em {arquivo.name}: {e}")

    return documentos

# Processar pasta de documentos
docs = processar_documentos("/home/diego/documentos/empresa")
print(f"Total convertido: {len(docs)} documentos")

Depois de converter, você pode usar os textos Markdown para criar embeddings, indexar em um banco vetorial e construir um chatbot que responde perguntas sobre seus documentos — tudo usando Python e JSON para armazenar os metadados.

Processamento em lote com tratamento de erros

Para produção, é importante tratar erros e logging adequadamente:

import logging
from markitdown import MarkItDown

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

conversor = MarkItDown()

def converter_com_fallback(caminho: str) -> str | None:
    """Converte arquivo com tratamento de erros robusto."""
    try:
        resultado = conversor.convert(caminho)
        if not resultado.text_content or len(resultado.text_content.strip()) < 10:
            logger.warning(f"Conteúdo vazio ou muito curto: {caminho}")
            return None
        logger.info(f"Convertido com sucesso: {caminho} ({len(resultado.text_content)} chars)")
        return resultado.text_content
    except FileNotFoundError:
        logger.error(f"Arquivo não encontrado: {caminho}")
    except PermissionError:
        logger.error(f"Sem permissão para ler: {caminho}")
    except Exception as e:
        logger.error(f"Erro ao converter {caminho}: {type(e).__name__}: {e}")
    return None

Comparação com alternativas

O grande diferencial do MarkItDown é a simplicidade: uma API unificada para todos os formatos, com saída consistente em Markdown. Bibliotecas como unstructured oferecem mais controle, mas com complexidade muito maior.

Limitações e cuidados

Nem tudo são flores. Alguns pontos de atenção:

• PDFs escaneados — o MarkItDown não faz OCR nativo; você precisa de ferramentas adicionais como Tesseract
• Tabelas complexas — tabelas com células mescladas ou layouts irregulares podem perder estrutura
• Arquivos grandes — documentos com centenas de páginas podem consumir bastante memória
• Dados sensíveis — ao usar a integração com LLMs para imagens, os dados são enviados para a API do provedor

Para arquivos grandes, considere processar em chunks ou usar multiprocessing para paralelizar a conversão.

Quando usar o MarkItDown

O MarkItDown brilha em cenários como:

• Pipelines de RAG — indexar documentos corporativos para chatbots internos
• Automação de relatórios — converter relatórios de diferentes formatos para um padrão unificado
• Pré-processamento para LLMs — preparar dados para fine-tuning ou análise
• Migração de conteúdo — converter documentação legada para Markdown

Conclusão

O MarkItDown preencheu uma lacuna importante no ecossistema Python: uma forma simples e confiável de converter qualquer documento para Markdown, pronto para uso com LLMs. A API unificada, o suporte a dezenas de formatos e a integração com modelos de visão fazem dele uma ferramenta essencial para quem trabalha com IA e automação em 2026.

Se você quer explorar mais sobre automação de documentos, confira nosso guia de Python e Excel e como trabalhar com manipulação de arquivos. E para quem quer criar agentes de IA que usam MarkItDown como ferramenta, o artigo sobre LangGraph e agentes é o próximo passo natural.

Desenvolvedores que usam Kotlin para projetos Android podem se interessar por como o ecossistema mobile se integra com backends Python em kotlin.dev.br. Para quem explora Rust em ferramentas de alta performance como o próprio ruff e uv, vale visitar rustlang.com.br.