# MarkItDown: converter PDF e Word em texto para IA
> Como instalar o MarkItDown, converter documentos em texto, tratar PDFs e digitalizações, ligar ao Claude por MCP e conhecer as limitações.
Source: https://ailoot.ai/blog/pt-pt/markitdown-pdf-word-to-text/
Canonical: https://ailoot.ai/blog/pt-pt/markitdown-pdf-word-to-text/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-171
Revision: sha256-cffd4a14feaed267a1846392931ee17b8e95d1aecd9d897e5f17eb7046ae46b6
Principais conclusões
O MarkItDown é um utilitário gratuito da Microsoft que converte ficheiros Word, Excel, apresentações e PDF em texto estruturado para IA. Analisa ficheiros Office corretamente numa fração de segundo. Transforma PDFs com esquemas complexos numa confusão e, no caso de uma digitalização, devolve um ficheiro vazio com código de saída zero. Abaixo encontra um comando de instalação funcional, medições em documentos com texto cirílico e uma regra para saber quando utilizar outra ferramenta.
Consulte mais instruções na [documentação da Ailoot](https://ailoot.ai/docs/).
## O que é o MarkItDown e para que serve?
Principais conclusões
O MarkItDown é um utilitário Python da Microsoft que lê um ficheiro e devolve o seu conteúdo como texto estruturado. Os títulos continuam a ser títulos e as tabelas continuam a ser tabelas. Está num repositório público do GitHub sob a licença MIT, instala-se com um único comando e processa tudo no seu computador. Tem uma única função: preparar um documento para que uma IA veja não só as palavras, mas também a estrutura.
Envia um contrato, um relatório ou uma exportação contabilística a uma IA e recebe uma resposta sem qualquer relação com o documento. Normalmente, a causa não é o modelo. O ficheiro contém um formato: o Word é um arquivo com marcação, o Excel é uma folha de cálculo com ligações entre células e o PDF é um conjunto de caracteres com coordenadas numa página. O modelo trabalha com texto e alguém tem de o extrair.
É isso que o MarkItDown faz. O repositório está em [github.com/microsoft/markitdown](https://github.com/microsoft/markitdown), sob a licença MIT, pelo que o pode utilizar sem restrições. A 18 de agosto de 2026, tinha 174,412 estrelas e 12,756 forks; a versão mais recente, 0.1.7, foi lançada a 29 de julho. O projeto continua ativo, embora o foco tenha passado do desenvolvimento para a manutenção: tem 481 pull requests abertas, face a 183 integradas ao longo de toda a sua história.
Os programadores descrevem o objetivo da seguinte forma:
O MarkItDown é um utilitário Python leve para converter ficheiros de vários formatos em Markdown, para utilização com grandes modelos de linguagem e processos relacionados de análise de texto.
— Microsoft, descrição do projeto (traduzida), https://github.com/microsoft/markitdown
A frase seguinte da descrição explica metade das queixas que as pessoas fazem sobre a ferramenta:
Embora o resultado seja muitas vezes bastante razoável e fácil de ler, destina-se a ferramentas de análise de texto e poderá não ser a melhor opção para conversões de alta fidelidade de documentos destinados à leitura humana.
— Microsoft, descrição do projeto (traduzida), https://github.com/microsoft/markitdown
O resultado é matéria-prima para um modelo. Não será um documento bonito, e o projeto diz isso claramente logo na primeira secção.
A descrição explica diretamente por que motivo utiliza Markdown: os principais modelos já “falam” esta linguagem de marcação e incluem-na nas respostas sem que lhes seja pedido, porque viram enormes volumes dela durante o treino. A marcação também é compacta: três sinais de cardinal para um título, em vez de uma dúzia de linhas de metadados.
## Em que difere o MarkItDown de um conversor comum?
Principais conclusões
Conversores como o pandoc traduzem uma linguagem de marcação para outra e preservam o esquema para as pessoas. O pandoc não aceita PDF como entrada. O MarkItDown resolve o problema oposto: extrai conteúdo de um ficheiro Office e organiza-o para que um modelo o compreenda imediatamente, sem desperdiçar tokens. Preservar o esquema visual não é o seu objetivo, e é essa a diferença.
A diferença percebe-se com um exemplo. Pegue numa pasta com vinte PDFs e tente processá-los com o pandoc. Não vai funcionar: o [pandoc](https://pandoc.org/) consegue gerar PDFs como saída, mas não consegue lê-los como entrada. E esta situação — “tenho uma pilha de documentos; passe-os ao modelo” — é a mais comum.
Os autores do MarkItDown comparam-no com o textract, uma biblioteca que simplesmente extrai texto de qualquer origem. A diferença é que o MarkItDown tenta preservar a estrutura: títulos, listas, tabelas e ligações.
| Funcionalidade | pandoc | MarkItDown |
|----|----|----|
| Lê PDFs | não | sim, com ressalvas |
| Lê Word, Excel e apresentações | parcialmente | sim |
| Público-alvo do resultado | pessoas | modelos |
| Principal valor | fidelidade ao esquema | estrutura e baixo número de caracteres |
| Instalação | programa autónomo | um comando Python |
A conclusão prática é simples. Se precisa de converter um artigo num esquema para publicação, utilize o pandoc. Se precisa que uma IA compreenda vinte contratos, utilize o MarkItDown.
## Como instalar o MarkItDown sem obter a primeira versão?
Principais conclusões
Com a versão 0.1.8, o comando na descrição do projeto instala a versão mais recente em Python 3.14 e 3.12; isto foi novamente verificado em oito ambientes limpos. Em Python 3.15, em Macs Intel com Python 3.14 e em Macs com versões mais antigas do macOS com Python 3.13 e 3.14, continua a ocorrer uma reversão silenciosa para a versão 0.0.2, a segunda versão da história do projeto. Nestes casos, o instalador indica que a instalação foi bem-sucedida. Por isso, utilize Python 3.12, indique pelo nome os formatos de que precisa e verifique imediatamente o número da versão.
Primeiro, o comando certo; depois, porque é que é o certo.
1. ### Verifique a versão do Python
Python 3.12 é a opção mais fiável: a versão mais recente do MarkItDown instala-se em todos os ambientes testados com essa versão. O comando `python3 --version` mostra-lhe qual tem. Em Macs Intel ou Macs com uma versão mais antiga do macOS, Python 3.13 e 3.14 podem reverter silenciosamente para uma versão anterior; Python 3.15 ainda não é suportado, como explicamos abaixo.
2. ### Instale com os formatos indicados
Execute `pip install 'markitdown[pdf,docx,xlsx,pptx]'`. As aspas são necessárias; caso contrário, a shell interpreta os parênteses retos. Num Mac Intel, acrescente o sinalizador `--prefer-binary` depois de `install`.
3. ### Confirme imediatamente que foi instalado
Execute `markitdown --version`. A resposta deverá ser `markitdown 0.1.8` ou posterior. Um número inferior significa que a instalação reverteu para uma versão anterior; esta secção explica porquê.
```bash
pip install 'markitdown[pdf,docx,xlsx,pptx]'
markitdown --version
```
A descrição do projeto apresenta `pip install 'markitdown[all]'` como o comando principal, para instalar tudo de uma vez. A 28 de setembro de 2026, uma semana depois do lançamento da versão 0.1.8, foram testadas quatro variantes em ambientes limpos num Mac com Apple Silicon, com Python 3.14.6 e 3.12.12:
| Comando | Instalado em Python 3.14 | Instalado em Python 3.12 |
|----|----|----|
| `pip install markitdown` | 0.1.8 | 0.1.8 |
| `pip install 'markitdown[pdf,docx,xlsx,pptx]'` | 0.1.8 | 0.1.8 |
| `pip install 'markitdown[all]'` | 0.1.8 | 0.1.8 |
| `pip install 'markitdown[all]==0.1.8'` | 0.1.8 | 0.1.8 |
As oito instalações terminaram com “Successfully installed” e `markitdown --version` devolveu 0.1.8 em todos os casos. Em agosto, quando a versão mais recente era a 0.1.7, o terceiro comando instalou a versão 0.0.2 em Python 3.14, lançada a 8 de março de 2025 — a segunda versão da história do projeto. Atualmente, existem onze versões estáveis, da 0.0.1 à 0.1.8, e vinte e seis, incluindo pré-lançamentos.
A causa estava na cadeia de dependências. Na versão 0.1.7, o extra `[all]` inclui uma biblioteca de legendas do YouTube de uma série de versões específica, e todas as versões dessa série declaram que não funcionam em Python 3.14. O instalador rejeita-as e, como não há uma versão fixada, recua pelas versões do MarkItDown até encontrar uma que possa instalar. Encontra a 0.0.2 e instala-a, colocando no seu computador uma versão com ano e meio. Na versão 0.1.8, o requisito da biblioteca de legendas foi atualizado para uma série compatível com 3.14, e a reversão deixou de acontecer nesse ponto.
O mecanismo continua a existir. Se o instalador não encontrar um componente necessário para o seu sistema, recua silenciosamente para a versão 0.0.2 da mesma forma. Nas versões recentes, esse componente é o motor onnxruntime utilizado pelo detetor de tipos de ficheiros. No Mac, é compilado da seguinte forma: para Python 3.12, macOS 11 e posterior; para 3.13, macOS 13; para 3.14, apenas Apple Silicon com macOS 14 ou posterior. Se o seu Mac não cumprir estes requisitos, até o comando simples `pip install markitdown` instala a versão 0.0.2. Um teste num Mac Intel com Python 3.14 através do Rosetta produziu exatamente este resultado: “Successfully installed”, sem avisos e com a versão 0.0.2 instalada.
Os Macs Intel têm outra complicação. Desde junho de 2026, a biblioteca cryptography, necessária para ler PDFs, é lançada sem uma versão pré-compilada para este processador, pelo que o instalador tenta compilá-la a partir do código-fonte. Acrescente o sinalizador `--prefer-binary` ao comando e será utilizada a versão anterior, com um pacote pré-compilado. Nos testes em Python 3.13 num Intel, isso instalou a versão 0.1.8 e o PDF abriu. O sinalizador instala cryptography 48.0.1, que tem três vulnerabilidades conhecidas: na desencriptação PKCS#7 e na verificação da cadeia de certificados. O MarkItDown só a utiliza para desencriptar PDFs encriptados, e a leitura de documentos não chega a essas partes.
Em Python 3.15, a reversão acontece por dois motivos. A versão 0.1.8 declara suporte apenas entre 3.10 e 3.14, e ainda não existe um motor para 3.15. A resolução do instalador para 3.15 confirma-o: tanto o comando simples como o comando com formatos instalam a mesma versão 0.0.2.
Um aviso de reversão tem este aspeto, uma linha por cada extra no comando:
```
WARNING: markitdown 0.0.2 does not provide the extra 'all'
```
A linha perde-se entre dezenas de linhas de transferência e não indica qual é a versão substituída. Com um comando simples, sem extras, nem sequer aparece um aviso. A mensagem final é animadora: “Successfully installed.”
Instalar sem extras também não é solução. O pacote base instala-se, mas não consegue abrir PDFs:
```
PdfConverter recognized the input as a potential .pdf file, but the
dependencies needed to read .pdf files have not been installed. To resolve
this error, include the optional dependency [pdf] or [all] when installing
MarkItDown. For example:
* pip install 'markitdown[pdf]'
* pip install 'markitdown[all]'
```
A própria ferramenta recomenda `[all]` e, com a versão 0.1.8, esse conselho voltou a funcionar em Python 3.14 e 3.12. Ainda assim, é melhor indicar os formatos pelo nome: `[all]` acrescenta mais cerca de quinze pacotes e cerca de 55 megabytes, incluindo uma biblioteca Azure em pré-lançamento e a própria cadeia de dependências do YouTube que já interrompeu a instalação uma vez.
O instalador trata sozinho do pré-lançamento Azure. Normalmente, o pip ignora pré-lançamentos, mas neste caso o requisito indica explicitamente um pré-lançamento, pelo que o instala. Foram testadas quatro versões do pip, da 23.2 à 26.2, em Python 3.12; todas selecionam a versão 0.1.8.
Atenção
Imediatamente após a instalação, execute `markitdown --version`. Demora cinco segundos e é a única forma de saber se instalou aquilo que pediu. O aviso de sucesso não significa nada neste caso.
Em agosto, uma nova instalação noutro ambiente limpo deu o mesmo resultado: 0.0.2 e a palavra “Successfully”.
Convém conhecer antecipadamente alguns pormenores práticos.
É bastante volumoso: uma instalação base ocupa 143 megabytes; com quatro formatos, 303. O componente mais pesado, com 81 megabytes, é o detetor de tipos de ficheiros, incluído mesmo na instalação básica. Isso não importa num portátil, mas importa numa função na nuvem com limite de tamanho.
Não conte com espelhos como alternativa. Um espelho testado forneceu um índice e os ficheiros do MarkItDown estavam disponíveis, mas faltava uma dependência necessária, pelo que a instalação falhou em Python 3.14 e 3.12.
A instalação é um pormenor comparada com o problema principal. Mais frequentemente, uma IA produz disparates porque foi colocado no seu contexto algo errado ou numa representação errada. A capacidade de decidir o que dar a um modelo antes de uma tarefa chama-se engenharia de contexto, e a preparação de documentos faz parte dela.
## Como converter o primeiro documento em texto?
Principais conclusões
Um comando no terminal: o nome do programa e o caminho do ficheiro. Por predefinição, o resultado é apresentado diretamente na janela, pelo que o pode guardar num ficheiro. Existem três métodos: saída para a consola, escrita com um sinalizador ou passagem do ficheiro como fluxo. Para o integrar nos seus próprios scripts, existe um wrapper Python de três linhas, que também aceita URLs.
A opção mais curta:
```bash
markitdown dogovor.docx
```
O texto é apresentado no terminal. Para o guardar num ficheiro, há duas formas:
```bash
markitdown dogovor.docx -o dogovor.md
markitdown dogovor.docx > dogovor.md
```
A diferença é insignificante no Mac e no Linux, mas importa no Windows: o redirecionamento com `>` pode bloquear o programa quando a saída contém texto cirílico.
Pode passar um ficheiro como fluxo; nesse caso, a indicação da extensão é útil:
```bash
cat dogovor.docx | markitdown -x docx
```
Estes são os principais sinalizadores da ajuda da versão 0.1.8:
| Sinalizador | O que faz |
|----|----|
| `-o`, `--output` | escreve o resultado num ficheiro em vez de o apresentar na janela |
| `-x`, `--extension` | indicação da extensão quando o ficheiro é passado como fluxo |
| `-m`, `--mime-type` | indicação do tipo de conteúdo |
| `-c`, `--charset` | indicação da codificação de caracteres |
| `-d`, `--use-docintel` | processamento através do serviço pago na nuvem da Microsoft |
| `-v`, `--version` | mostra a versão |
A mesma ajuda lista mais três sinalizadores úteis, todos testados: `--list-plugins` mostra os plugins instalados, `-p` ativa-os numa execução específica e `--keep-data-uris` mantém na saída as imagens incorporadas no documento (são recortadas por predefinição). Os restantes são definições dos serviços na nuvem da Microsoft.
O wrapper Python tem três linhas:
```python
from markitdown import MarkItDown
md = MarkItDown()
print(md.convert("ostatki.xlsx").text_content)
```
A mesma chamada aceita um URL. Uma página simples devolveu texto limpo com 167 caracteres, incluindo um título e uma ligação, sem o menu nem o rodapé:
```python
r = md.convert("https://example.com")
```
## Que formatos entende o MarkItDown e o que significa isso na prática?
Principais conclusões
A descrição do projeto lista uma grande variedade: ficheiros Office, PDFs, imagens, áudio, arquivos, ligações do YouTube e livros digitais. Três elementos não funcionam como parecem. A versão gratuita não reconhece texto em imagens. A fala é enviada para um motor em inglês. Os ficheiros que não consegue analisar desaparecem dos arquivos sem aviso.
Uma tabela-resumo do que é anunciado e do que acontece na prática.
| Formato | Anunciado | O que acontece na prática |
|----|----|----|
| Word, Excel, apresentações | sim | funciona corretamente; é o seu ponto forte |
| CSV, JSON, XML, HTML | sim | funciona, mas o CSV tem um problema com o delimitador |
| PDF | sim | depende do esquema: uma coluna é reconstruída, duas desmoronam-se |
| Imagens | “metadados e reconhecimento” | sem reconhecimento, apenas metadados ou um modelo visual pago |
| Áudio | “transcrição de fala” | é enviado para o motor em inglês da Google |
| Arquivos ZIP | “percorre o conteúdo” | tudo o que não consegue analisar desaparece silenciosamente |
| Ligações do YouTube | sim | apenas ligações completas no formato `''?...` |
| Livros digitais EPUB | sim | funciona |
Vejamos três elementos em mais pormenor.
Imagens. A descrição inclui a palavra OCR, pelo que as pessoas esperam que o programa leia texto numa fotografia. Não o faz. Lê metadados com um programa separado, o exiftool, e, se ligar um modelo visual com a sua própria chave, pode enviar-lhe a imagem para criar uma descrição.
Áudio. A transcrição de fala está disponível, mas o idioma não é transmitido e o motor espera inglês por predefinição. Também chama o ponto final gratuito não oficial da Google, limitado a cerca de cinquenta pedidos por dia por chave.
Arquivos. O programa descompacta ficheiros ZIP e percorre os ficheiros contidos, concatenando os resultados. Se não conseguir analisar um ficheiro, o erro é capturado e suprimido. O ficheiro simplesmente não aparece no resultado e não saberá que foi omitido.
## O que acontece com documentos que contêm texto cirílico?
Principais conclusões
A versão mais recente foi testada em três ficheiros com texto cirílico: um contrato Word, uma folha de inventário Excel e uma apresentação. O texto cirílico e o número mantiveram-se intactos nos três. Há problemas em três situações: ficheiros CSV com ponto e vírgula, formatação da moeda nas células Excel e saída na consola do Windows. As três têm solução.
Os ficheiros abaixo foram criados especificamente para os testes; os dados são fictícios.
A folha de inventário Excel também ficou perfeita, com o nome da folha convertido num título:
```markdown
## Stock
| Item | In stock | Reserved | Available |
| --- | --- | --- | --- |
| Coffee beans, kg | 420 | 38 | 382 |
| Loose-leaf tea, kg | 180 | 52 | 128 |
```
A apresentação transformou-se em texto, com os números dos diapositivos apresentados como anotações e os títulos dos diapositivos convertidos em títulos. O texto cirílico também está intacto. A afirmação generalizada de que “o MarkItDown não entende cirílico” é falsa.
Agora, vejamos as três situações em que algo corre mal.
CSV com ponto e vírgula. Foram processadas duas exportações de faturas idênticas para comparação. A que usava vírgulas produziu uma tabela correta com quatro colunas. Com ponto e vírgula, a linha inteira fica numa única célula.
A linha inteira acabou numa única célula. A codificação foi reconhecida corretamente e não houve erro; o sinalizador `-c` não ajuda. O modelo receberá esta tabela e não perceberá qual valor é o montante e qual é o estado. Exporte novamente o ficheiro com delimitador de vírgula explícito e codificação correta, preservando o original. Não substitua pontos e vírgulas globalmente: separadores em texto entre aspas e vírgulas decimais podem integrar um valor. Se não puder voltar a exportar, interprete o original com o delimitador real e grave outro CSV com uma ferramenta que preserve aspas e valores das células. Antes da análise, compare números de colunas e linhas e totais de controlo com a exportação original.
Formatação da moeda no Excel. O símbolo da moeda fica guardado nas definições de apresentação da célula e não faz parte do próprio valor. Os responsáveis pelo projeto confirmaram a causa. Isto importa num preçário ou numa fatura: o modelo verá números sem saber a que moeda correspondem.
Consola do Windows. Com ficheiros que contêm caracteres não latinos, o programa pode falhar.
O registo do erro mostra a codificação `cp1251`, ou seja, a consola do Windows. O documento é analisado corretamente; o que falha é a impressão do resultado na janela do terminal. Há duas soluções:
```powershell
markitdown dogovor.docx -o dogovor.md
$env:PYTHONUTF8 = "1"; markitdown dogovor.docx > dogovor.md
```
A primeira evita por completo a consola; a segunda faz com que o Python escreva em UTF-8. Já foram submetidas pelo menos seis propostas para corrigir o problema na própria ferramenta: algumas foram encerradas sem serem integradas e as restantes continuam abertas. Por isso, terá de contornar o problema.
Um quarto sintoma surge nos PDFs: sequências como `(cid:1090)` em vez de letras. Isto significa que o ficheiro tem uma tabela de tipos de letra não normalizada e que não foi possível descodificar os caracteres. Não vale a pena processar esse documento com o MarkItDown; precisa de outra ferramenta.
## Porque é que um PDF fica uma confusão?
Principais conclusões
Um PDF não contém estrutura, apenas caracteres com coordenadas na página. O texto com uma coluna é recomposto de forma razoável. Duas colunas transformam-se numa confusão: as linhas juntam-se entre colunas, as palavras colam-se e o esquema transforma-se em tabelas que nunca existiram no documento. A ferramenta não identifica títulos em PDFs — isso é evidente tanto no código-fonte como em medições independentes.
Para o teste, foi processado um artigo científico de 2.16 megabytes com duas colunas. O código de saída foi zero; após 0.9 segundos, o resultado continha 88,000 caracteres, quase todos sem sentido. Oitenta e oito mil caracteres dão a impressão de que tudo correu bem. Até abrir o ficheiro:
```
| | Hybrid | | OCR-LLM | | Framework |
| --- | ------ | -------- | ----------- | --- | ---------- |
...
Informationextractionfromcopy-heavydoc-
5202 tcO 11 ]LC.sc[ 1v83101.0152:viXra
```
Três coisas correram mal ao mesmo tempo. O esquema de duas colunas tornou-se em tabelas que não existem no artigo. As palavras colaram-se sem espaços. A última linha é uma barra lateral vertical da página, extraída ao contrário.
Depois veio a parte divertida. O artigo de teste acabou por ser precisamente o trabalho que avaliava o MarkItDown e o comparava com outras ferramentas. A ferramenta converteu o parágrafo que relatava as suas próprias medições para isto:
```
cues. This name-matching error could be miti- OCRpreprocessingoverhead(0.056s),whileDo-
gatedthroughpromptengineeringtoprovidemore clingandMinerUadoptmorecomputationallyin-
explicit matching instructions or fine-tuning the tensive strategies with OCR latencies of approxi-
```
As colunas esquerda e direita foram unidas linha a linha. Um modelo que receba isto lerá metade de uma frase de um parágrafo e metade de outro.
A causa é técnica e simples. O Word guarda explicitamente “isto é um título” e “isto é uma célula de tabela”. Um PDF guarda “isto é um carácter” e “estas são as coordenadas na página”. Reconstruir a estrutura a partir das coordenadas é uma tarefa difícil e independente, e o MarkItDown mal tenta fazê-lo. O código-fonte de análise de PDF não deteta títulos: se uma página não for reconhecida como formulário ou tabela, todo o documento passa por uma extração de texto básica.
Os utilizadores relatam isto regularmente no repositório do projeto, incluindo em artigos científicos e tabelas.
A ferramenta não deteta um único título em PDFs, exatamente como mostra o código-fonte.
A afirmação “o MarkItDown atinge 82% de precisão” circula online sem qualquer metodologia. Tentar encontrar a fonte original não leva a lado nenhum: a cadeia de ligações termina numa página que não carrega. Não pode ser considerada uma medição.
## O que acontece com um contrato digitalizado?
Principais conclusões
Nada. O ficheiro é processado, o programa indica que a operação foi bem-sucedida e o resultado contém zero caracteres. Sem erro nem aviso. Isto foi testado duas vezes num PDF criado a partir de uma imagem e, separadamente, na própria imagem — o resultado foi o mesmo. A ferramenta extrai texto que já está armazenado como texto no ficheiro; a versão gratuita não tem capacidade de reconhecimento.
Este comportamento é mais perigoso do que os restantes porque não parece uma falha.
Para o teste, foi criado um PDF a partir de uma imagem com texto — exatamente o que se obtém quando se fotografa ou digitaliza um contrato. A execução foi repetida para excluir o acaso:
| Entrada | Código de saída | Caracteres na saída | Mensagem de erro |
|----|----|----|----|
| PDF de imagem, execução 1 | 0 | 0 | nenhuma |
| PDF de imagem, execução 2 | 0 | 0 | nenhuma |
| Imagem PNG diretamente | 0 | 1 (mudança de linha) | nenhuma |
Zero caracteres e zero erros, duas vezes seguidas. Um código de saída zero significa “correu tudo bem” e qualquer script que verifique o sucesso pelo código de saída considerará o documento processado. Depois, o resultado vazio é enviado ao modelo, o modelo não vê nada e começa a inventar uma resposta do nada.
Atenção
Se processar documentos em lotes, verifique o comprimento do resultado. O código de saída não lhe dirá nada: um ficheiro vazio com código de saída zero é o aspeto de uma digitalização.
Há duas soluções, e ambas são pagas. A primeira é o sinalizador `-d`, que envia o documento para o serviço de reconhecimento na nuvem da Microsoft; o texto de ajuda do sinalizador indica explicitamente que é necessário um ponto final de serviço válido. A segunda é um pacote complementar separado que envia as páginas para um modelo visual através da sua chave, pelo que paga ao fornecedor do modelo por cada página. Desde abril de 2026, uma discussão aberta sobre o segundo método indica que apenas é processada a primeira página de uma digitalização com várias páginas.
Também pode executar um modelo de reconhecimento no seu próprio computador, mas isso é um projeto separado.
Para um documento pontual, é mais fácil abri-lo e copiar o texto manualmente. Para um fluxo de digitalizações, precisa de uma ferramenta com reconhecimento integrado.
## Pode simplesmente carregar o ficheiro para um conversor online?
Principais conclusões
Tecnicamente, sim; existem muitos domínios com este nome. Mas nenhum está associado à Microsoft. A afirmação “o ficheiro nunca sai do seu browser” pode ser verificada com um clique e nem sempre é verdadeira. Antes de carregar um contrato ou uma exportação com nomes de pessoas, veja por si para onde vai o ficheiro.
“MarkItDown online” é uma das sugestões de pesquisa mais comuns e há sites que o oferecem. A ferramenta original da Microsoft não tem qualquer site; só está disponível como programa que instala por sua iniciativa. Qualquer coisa com um nome semelhante que abra num browser foi criada por outra pessoa.
Pode verificar um serviço destes num minuto: abra as ferramentas de programador no separador dos pedidos de rede, carregue qualquer ficheiro inofensivo e veja se é enviado para um servidor. Se for, a afirmação de que o processamento ocorre no browser é falsa, por mais confiança que demonstre nas perguntas frequentes.
Atenção
Um contrato, uma fatura ou uma exportação que contenha nomes de funcionários inclui dados pessoais. Se enviar esse ficheiro para o site de terceiros, é o utilizador que o transmite. Um utilitário local evita esse problema: o ficheiro não sai do seu computador.
É por isso que o MarkItDown é valorizado quando não se podem enviar documentos para fora da organização. Numa discussão, alguém descreveu a sua situação: programas arbitrários eram proibidos no portátil de trabalho, mas as bibliotecas Python eram permitidas, e o utilitário local acabou por ser a única opção disponível.
## Quanto poupa realmente o MarkItDown?
Principais conclusões
A principal vantagem é que o modelo consegue compreender o documento. Também há uma diferença de tamanho: comparar o peso da marcação dentro dos ficheiros Office com o tamanho do texto extraído mostra uma redução de cinco a sete vezes. Também remove tudo o que o modelo não precisa de ler: descrições de tipos de letra, margens e cores das células.
Um ficheiro Office é estruturado como um arquivo que contém marcação. Se descompactar os três ficheiros de teste e comparar o tamanho da parte que contém o conteúdo com o tamanho do resultado, obtém o seguinte:
| Ficheiro | Marcação interna | Texto extraído | Vezes menor |
|-----------------|-----------------|---------------|-----------------------|
| Contrato Word | 3,701 bytes | 711 bytes | 5.2 |
| Folha de cálculo Excel | 1,561 bytes | 262 bytes | 6.0 |
| Apresentação | 2,203 bytes | 296 bytes | 7.4 |
Os ficheiros são pequenos; as proporções serão diferentes nos maiores e não existe um único valor de poupança. Quando surgirem números redondos em artigos comparativos, pergunte qual foi a metodologia.
Os próprios programadores também falam de poupanças: a descrição do projeto afirma especificamente que as convenções Markdown são muito económicas em termos de caracteres. É verdade, mas não deve ser o principal argumento de venda. A diferença entre “o modelo recebeu três mil caracteres em vez de quinze mil” e “o modelo recebeu uma estrutura clara em vez de um amontoado” é de outra ordem. A primeira poupa dinheiro; a segunda determina se a resposta fará sentido.
Se o consumo de contexto for uma preocupação, este assunto é abordado separadamente: [Para onde vão os tokens no Claude](https://ailoot.ai/blog/pt-pt/where-claude-code-tokens-go/) e [quantos estão incluídos em cada plano](https://ailoot.ai/blog/pt-pt/claude-pro-max-usage-limits/).
## Como ligar MarkItDown a um agente de inteligência artificial no Claude Code por MCP? {#como-ligar-o-markitdown-ao-claude-através-de-mcp}
Principais conclusões
O projeto tem um pacote separado que executa um servidor MCP com um único comando: forneça um caminho de ficheiro e recebe texto. Em setembro de 2026, o pacote foi finalmente atualizado para 0.0.1a7, mas a compilação continua a ser um pré-lançamento e envia telemetria para a Microsoft por predefinição. O comando abaixo liga-o através do uv, fixa a versão, utiliza Python 3.12 e desativa a telemetria. Não existe autenticação e, de acordo com a própria documentação, o servidor pode ler qualquer ficheiro acessível ao utilizador que o iniciou.
MCP é uma forma de dar a uma IA uma ferramenta externa que pode utilizar por si própria. Para uma visão geral do mecanismo e de outros servidores, consulte a análise dos [servidores MCP para Claude Code](https://ailoot.ai/blog/pt-pt/mcp-servers-claude-code/).
O servidor MarkItDown disponibiliza exatamente uma ferramenta: converter um documento em texto. Aceita um caminho de ficheiro local, o URL de uma página ou dados incorporados diretamente no pedido.
Liga-se ao Claude Code com um único comando, fixando a versão do servidor. Precisa do gestor de pacotes uv:
```bash
claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list
```
A resposta ao segundo comando deverá mostrar “Connected” para `markitdown`. A primeira execução transfere cerca de setenta pacotes e demora até um minuto; depois disso, o servidor inicia-se em um a um segundo e meio.
Estas são as ressalvas, verificadas manualmente.
A compilação `0.0.1a7` foi lançada a 14 de setembro de 2026. Antes disso, o servidor tinha permanecido na versão `0.0.1a4`, de maio de 2025, durante mais de um ano. O número da versão mais recente continua a ser um pré-lançamento.
Não se instala em todos os sistemas com uma versão recente do Python. O motor onnxruntime de que depende só está disponível para Python 3.14 no Mac com Apple Silicon e macOS 14 ou posterior, pelo que a instalação falha em Macs Intel e em macOS 13 ou anterior com Python 3.14. Num Mac com Apple Silicon, o servidor foi executado em Python 3.14, 3.13 e 3.12, e instalou-se nas três versões. O comando utiliza `UV_PYTHON=3.12`: há pacotes pré-compilados para 3.12 no Windows, Linux e Macs com Apple Silicon e, se não tiver essa versão de Python, o uv irá transferi-la. Também há uma ressalva para Macs Intel: o uv irá compilar a biblioteca cryptography a partir do código-fonte porque, desde junho de 2026, não existe um pacote pré-compilado para Intel. A instalação demora mais e pode falhar.
A versão do MarkItDown instalada depende da versão do uv. A partir do MarkItDown 0.1.6, o extra `[all]` exige um pré-lançamento da biblioteca Azure: o uv 0.12 e posterior instala-o e instala a versão mais recente do MarkItDown, 0.1.8, enquanto as versões mais antigas do uv recuam para a 0.1.5. Verifique a versão do uv com `uv --version`.
Há duas coisas que são enviadas para fora do computador. A primeira é a telemetria: no Mac e no Linux, o motor onnxruntime dentro do servidor envia-a à Microsoft por predefinição. A variável `ORT_DISABLE_TELEMETRY=1` no comando desativa-a. No teste, o servidor ligou-se aos pontos finais de telemetria da Microsoft quando a variável não estava definida. Com a variável definida, não houve qualquer ligação durante o processamento de ficheiros a partir do disco.
A segunda é o áudio. O servidor envia ficheiros WAV, MP3, M4A e MP4 para o serviço de reconhecimento de fala da Google para transcrição por HTTP normal, sem encriptação. É melhor não lhe enviar gravações de conversas com clientes.
Um documento grande não cabe no servidor. Uma discussão aberta descreve uma resposta do servidor com 51,000 tokens que atingiu um limite de 25,000 tokens; a ferramenta não divide os ficheiros em partes.
E a segurança. A documentação do próprio pacote diz claramente:
O servidor não suporta autenticação e é executado com as permissões do utilizador que o iniciou. A ferramenta de conversão pode ser utilizada para ler qualquer ficheiro acessível ao utilizador do servidor ou quaisquer dados na rede.
— Microsoft, descrição do pacote markitdown-mcp (traduzida), https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp
Por outras palavras, um agente com esta ferramenta pode ler tudo o que consegue ler. Isso é aceitável para trabalhar no seu próprio computador. Não deve expor o servidor publicamente nem entregá-lo a um agente não fiável.
Atenção
A documentação do projeto não inclui uma configuração especificamente para Claude Code — descreve apenas o Claude Desktop e o arranque através de um contentor. Se encontrar online uma configuração pronta a utilizar descrita como “da documentação oficial” para Claude Code, saiba que não existe tal configuração no repositório.
Para o trabalho habitual, é mais fácil invocar o programa com um comando e colocar o texto resultante no projeto. O ficheiro fica junto dos restantes materiais, onde o modelo o pode consultar por iniciativa própria.
## Quando é mais honesto utilizar outra ferramenta?
Principais conclusões
A regra é simples: se a estrutura já estiver registada no ficheiro, utilize o MarkItDown — é o mais rápido e gratuito. Se for preciso reconstruir a estrutura a partir de uma imagem da página, utilize uma ferramenta com modelos de esquema. O Docling processa tabelas e esquemas complexos, o MinerU processa fórmulas e várias colunas e os serviços pagos na nuvem ajudam quando não há tempo para complicações.
Uma comparação baseada nas tarefas; as estrelas do GitHub não têm qualquer relevância:
| Ferramenta | Ponto forte | O que paga |
|----|----|----|
| MarkItDown | ficheiros Office, rapidez, gratuito | não consegue processar PDFs complexos nem digitalizações |
| Docling | tabelas e esquemas através de modelos especializados | dezenas de segundos por documento |
| MinerU | várias colunas, fórmulas, tabelas densas | instalação mais difícil |
| Marker | elevada precisão, fórmulas, ilustrações | exige uma placa gráfica e a licença restringe as receitas |
| unstructured | devolve a estrutura do documento em blocos com descrições | resultado mais difícil de utilizar |
| Analisadores na nuvem | sem configuração | dinheiro e envio do documento para fora do computador |
Há um detalhe sobre o Marker que os artigos comparativos omitem. Desde julho de 2026, o próprio código está sob uma licença permissiva, enquanto os pesos do modelo têm uma licença separada com um limite: a utilização é gratuita se a sua empresa não tiver ultrapassado cinco milhões de dólares em receitas nem o mesmo montante em financiamento angariado no ano anterior. Uma cláusula separada proíbe a utilização por quem esteja a criar um produto concorrente. Isto não importa à maioria dos leitores, mas é um motivo para uma empresa em crescimento ler a licença antes de o adotar.
Daí resulta um fluxo de trabalho prático em quatro passos:
1. Processe tudo com o MarkItDown — é gratuito e instantâneo.
2. Abra o resultado e verifique o tamanho.
3. Se o texto fizer sentido, a tarefa está concluída; não é preciso mais nada.
4. Se o resultado for confuso ou vazio, processe esse ficheiro específico com uma ferramenta mais exigente.
Assim, só paga o custo de tempo e complexidade nos documentos que precisam dele.
## Como integrar o MarkItDown no seu fluxo de trabalho?
Principais conclusões
A própria Anthropic indica a regra nas descrições das suas skills: utilize esta ferramenta para ler um documento. Não planeie edições com base nele. Eis três cenários em que compensa logo na primeira execução: analisar um lote de documentos semelhantes, adicionar materiais de referência permanentes a um projeto de IA uma única vez e preparar uma exportação de um sistema de contabilidade para análise.
A Anthropic utiliza o MarkItDown nas suas próprias skills prontas a utilizar para trabalhar com ficheiros Office, e essas skills definem claramente o limite que deve adotar por completo:
Inspecione rapidamente uma folha: markitdown file.xlsx. As coordenadas das células não estão disponíveis, pelo que não planeie edições com base nisto.
— Anthropic, descrição da skill para trabalhar com tabelas (traduzida), https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md
As referências a células e páginas perdem-se no texto, pelo que não o pode utilizar para fazer alterações ao ficheiro de origem. Eis três cenários.
Um lote de documentos semelhantes — autos, faturas, formulários, candidaturas. Coloque-os numa pasta e execute-os com uma única linha:
```bash
for f in dokumenty/*.docx; do markitdown "$f" -o "text/$(basename "$f" .docx).md"; done
```
Depois, entregue ao modelo a pasta com os ficheiros de texto e peça-lhe que reúna as informações relevantes numa tabela. Isto funciona com ficheiros digitais; as digitalizações falham e detetá-las-á imediatamente pelo tamanho zero.
Materiais de referência permanentes do projeto — preçários, modelos de contrato, políticas, descrições de serviços. Converta-os em texto uma vez e coloque-os junto do projeto. Assim, o modelo pode lê-los em cada pedido e não precisa de anexar os ficheiros à conversa todas as vezes. O artigo sobre [carregar ficheiros para o Claude](https://ailoot.ai/blog/pt-pt/claude-file-upload/) explica a diferença em relação a carregar um ficheiro para a conversa.
Uma exportação de um sistema de contabilidade. Uma exportação Excel de um programa de contabilidade ou de uma conta bancária transforma-se numa tabela em um terço de segundo, e o modelo pode fazer cálculos com ela sem passos intermédios. Verifique que o CSV foi exportado ou interpretado com o delimitador, as aspas e a codificação reais e compare linhas, colunas e totais de controlo antes de o entregar ao modelo. Não normalize separadores com pesquisa e substituição. Registe também a moeda explicitamente: um símbolo guardado só na formatação de uma célula Excel não sobrevive à extração.
O processamento de PDFs grandes no terminal não consta desta lista. É uma questão separada relacionada com o uso do contexto, abordada no artigo sobre [PDFs no Claude Code sem perder tokens](https://ailoot.ai/blog/pt-pt/pdf-claude-code-markdown/). Se estiver a configurar o seu espaço de trabalho, comece por [instalar o Claude Code](https://ailoot.ai/blog/pt-pt/install-claude-code/).
Para começar já, execute `pip install 'markitdown[pdf,docx,xlsx,pptx]'`, processe o primeiro contrato Word que encontrar e verifique o tamanho do resultado. Em meio minuto, saberá se funciona com os seus ficheiros.
### Perguntas frequentes
O MarkItDown é gratuito?
Sim. Tem uma licença MIT, sem restrições de utilização comercial. Só paga por dois métodos opcionais: reconhecimento na nuvem da Microsoft através do sinalizador `-d` e descrições de imagens por um modelo visual através da sua própria chave. Tudo o resto é executado gratuitamente no seu computador.
Os dados são enviados para algum servidor?
Na conversão habitual de ficheiros Office e PDFs, não — tudo é processado localmente. Há três exceções: a transcrição de áudio passa pelo serviço da Google, o sinalizador `-d` envia o documento para a nuvem da Microsoft e as descrições de imagens são enviadas para um modelo através da sua chave. Nenhum destes métodos é ativado automaticamente.
Porque não consigo encontrar o comando markitdown após a instalação?
Na maioria dos casos, o programa foi instalado num ambiente que não consta do seu caminho de pesquisa. Verifique o caminho completo para o ficheiro dentro do ambiente. Outro caso comum é tê-lo instalado para uma versão de Python e estar a chamá-lo com outra. Há ainda outro problema: em versões do Python anteriores à 3.10, é instalado um pacote vazio sem erro de instalação.
O que devo fazer se vir `(cid:1090)` e cadeias semelhantes em vez de letras?
Trata-se de uma tabela de tipos de letra não descodificada dentro do PDF. As definições não resolvem o problema; tem de processar o ficheiro com outra ferramenta, como o Docling ou o MinerU. Para um documento pontual, é mais rápido copiar o texto manualmente a partir de um visualizador.
Posso processar uma pasta inteira de ficheiros de uma só vez?
Não existe um modo de pasta separado, mas pode fazê-lo com um ciclo de terminal de uma linha: for f in papka/\*.docx; do markitdown "\$f" -o "\$f.md"; done. Outra opção é colocar tudo num ZIP e fornecer o arquivo: o programa processará o conteúdo, mas os ficheiros que não conseguir analisar desaparecerão sem aviso.
Em que difere o resultado de copiar o texto à mão?
Preserva a estrutura. A cópia dá-lhe texto corrido, em que um título não se distingue de um parágrafo e uma tabela se desfaz. O MarkItDown preserva títulos, listas e tabelas, para que o modelo consiga distinguir cada elemento. A diferença é pequena num documento curto, mas decisiva em vinte.
O MarkItDown consegue abrir documentos protegidos por palavra-passe?
Não. Um ficheiro protegido por palavra-passe não abre e não é possível passar a palavra-passe ao programa. Tem de remover a proteção previamente na aplicação que a aplicou.
### Fontes
- [MarkItDown – repositório do projeto no GitHub](https://github.com/microsoft/markitdown)
- [MarkItDown no PyPI – versões e datas de lançamento](https://pypi.org/project/markitdown/)
- [markitdown-mcp – descrição do servidor MCP](https://github.com/microsoft/markitdown/tree/main/packages/markitdown-mcp)
- [Anthropic Skills – utilização do MarkItDown para tabelas](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md)
- [Docling – análise de documentos com modelos de esquema](https://docling-project.github.io/docling/)
- [MinerU – análise de esquemas complexos de PDF](https://github.com/opendatalab/MinerU)
- [Marker – licença dos pesos do modelo](https://github.com/datalab-to/marker/blob/master/MODEL_LICENSE)
- [pandoc – conversor de linguagens de marcação](https://pandoc.org/)
Quando estiver pronto, conheça a [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Posso corrigir um CSV com pontos e vírgulas substituindo-os todos por vírgulas?
Não. Texto entre aspas e formatos decimais podem conter esses caracteres. Exporte de novo com o delimitador pretendido ou use um leitor e escritor CSV com delimitador, codificação e aspas explícitos; verifique colunas, linhas e totais de controlo face ao original.
### Um código de saída zero significa que o PDF foi convertido de forma útil?
Não. O exemplo digitalizado do artigo devolveu uma saída vazia sem erro e um PDF complexo produziu texto ilegível. Abra o resultado e verifique a extensão e a estrutura; use uma ferramenta de reconhecimento ou disposição quando o texto estiver vazio ou deturpado.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.