MarkItDown Web Scraping: Converter Páginas para Markdown Pronto para LLM

Resumo:

• MarkItDown converte uma página HTML raspada em Markdown, mantendo os cabeçalhos, links e listas que um modelo de linguagem lê bem.
• O scraping fornece HTML na memória, então o guia utiliza convert_stream com um BytesIO e uma extensão explícita .html em vez de um caminho de arquivo.
• MarkItDown não possui uma camada de fetch que limpa blocos, então o Scrapeless recupera a página e o MarkItDown a converte.
• Na página de exemplo, 11.021 caracteres de HTML se tornam 2.973 caracteres de Markdown que começam com um cabeçalho real.
• O MarkItDown converte todo o documento para Markdown estruturado; use trafilatura em vez disso quando você quiser apenas o artigo principal com o boilerplate removido.
• Comece no plano gratuito do Scrapeless e converta sua primeira página.

Modelos de linguagem leem Markdown melhor do que HTML bruto. O Markdown carrega a estrutura que um modelo precisa, cabeçalhos, listas e links, sem a confusão de tags, blocos de script e estilos inline que preenchem uma página HTML. O MarkItDown, o conversor de documentos da Microsoft para Markdown, faz essa conversão e lida com HTML, PDF, documentos do Office e mais através de uma única interface. O que ele não faz é buscar a página, que é a metade de um fluxo de scraping que precisa ser fornecida.

Este guia combina os dois. A API de Scraping Universal Scrapeless recupera a página, e o MarkItDown converte o HTML retornado para Markdown. Cada número abaixo vem de uma execução real contra uma página pública.

O que o MarkItDown faz

O MarkItDown pega um documento e retorna Markdown. Sua razão de existir é a entrada de LLM: ele produz texto que mantém a estrutura em uma forma eficiente em termos de token, seguindo a amplamente implementada especificação CommonMark para o Markdown que emite. O repositório MarkItDown lista os formatos de entrada que aceita, que incluem HTML, PDF, Word, PowerPoint e imagens.

O que o MarkItDown não é é um scraper. Ele não tem navegador e nenhuma forma de passar por um desafio de acesso, então converte quaisquer bytes que você lhe fornecer. Obter esses bytes de uma página ao vivo, às vezes protegida, é um trabalho separado.

Instalar

O MarkItDown é uma única instalação via pip.

pip install markitdown

Defina sua chave Scrapeless no shell. Use a chave real no tempo de execução e mantenha o espaço reservado fora de seu código fonte.

export SCRAPELESS_API_KEY="sk_sua_chave_aqui"

Converter HTML raspado para Markdown

O scraping retorna uma string HTML, não um arquivo, então o ponto de entrada correto é convert_stream. Envolva o HTML em um BytesIO e passe file_extension=".html" para que o MarkItDown o analise como HTML. O Markdown convertido está em text_content do resultado.

import io
import json
import os
import urllib.request

from markitdown import MarkItDown

API_URL = "https://api.scrapeless.com/api/v2/unlocker/request"
TARGET = "https://quotes.toscrape.com/"


def fetch_html(url: str) -> str:
    payload = json.dumps(
        {"actor": "unlocker.webunlocker", "input": {"url": url, "js_render": False, "headless": False}}
    ).encode()
    request = urllib.request.Request(
        API_URL,
        data=payload,
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"], "Content-Type": "application/json"},
        method="POST",
    )
    with urllib.request.urlopen(request, timeout=90) as response:
        return json.loads(response.read())["data"]


html = fetch_html(TARGET)
result = MarkItDown().convert_stream(io.BytesIO(html.encode("utf-8")), file_extension=".html")
markdown = result.text_content

print(f"caracteres html bruto: {len(html)}")
print(f"caracteres markdown: {len(markdown)}")
print(f"começa com cabeçalho: {markdown.lstrip().startswith('#')}")
print("--- primeiras linhas do markdown ---")
for line in [line for line in markdown.splitlines() if line.strip()][:4]:
    print(line)

A execução relata os tamanhos e imprime o topo do Markdown.

caracteres html bruto: 11021
caracteres markdown: 2973
começa com cabeçalho: True
--- primeiras linhas do markdown ---
# [Citações para Raspagem](/)
[Login](/login)
“O mundo como o criamos é um processo do nosso pensamento. Ele não pode ser mudado sem mudar nosso pensamento.”
por Albert Einstein

A saída começa com um verdadeiro cabeçalho de Markdown e um link, e a primeira citação da página segue. A estrutura que o modelo pode usar sobrevive à conversão, e os 11.021 caracteres de HTML se reduzem a 2.973 caracteres de Markdown.

Por que Markdown para um LLM

O Markdown é o formato que a maioria dos modelos de linguagem foram treinados para ler, então cabeçalhos se tornam seções, links permanecem legíveis e listas continuam sendo listas, tudo isso com muito menos tokens do que o HTML original. Enviar HTML bruto, por outro lado, gasta tokens em tags e estilos inline que o modelo deve ignorar, e enterra a estrutura que ajuda o modelo a organizar o conteúdo. Converter para Markdown primeiro é um passo barato que compensa em cada chamada subsequente.

Onde o MarkItDown Para

O MarkItDown converte; ele não recupera além de um bloco, razão pela qual este guia o emparelha com uma ferramenta de recuperação. Passe ao MarkItDown o HTML de uma página protegida obtida com um cliente simples e ele converterá fielmente uma página de desafios em Markdown. O Scrapeless retorna o HTML renderizado real, e o MarkItDown converte isso. Quando um alvo constrói seu conteúdo com JavaScript, defina js_render como True na solicitação para que o HTML já contenha o conteúdo; deixe como False, como aqui, quando a marcação é renderizada no servidor.

MarkItDown e trafilatura solucionam problemas diferentes. O MarkItDown converte o documento inteiro para Markdown estruturado, mantendo a forma da página. O Trafilatura isola o artigo principal e elimina o boilerplate. Converta com o MarkItDown quando você quiser a página como Markdown; extraia com o trafilatura quando você quiser apenas o corpo do artigo.

Antes de executar isso em um site, leia seu robots.txt e termos. O Protocolo de Exclusão de Robôs diz quais caminhos um site pede que clientes automatizados evitem, e honrar isso mantém um pipeline de conversão sustentável. Para o padrão mais amplo, o guia sobre pipelines de conteúdo de IA mostra onde um passo de conversão como este se encaixa.

Pronto para converter suas próprias páginas? Crie uma conta Scrapeless gratuita e altere a URL de destino.

Conclusão

Alimentar um modelo com Markdown em vez de HTML é uma pequena mudança com um retorno real, e leva duas ferramentas: Scrapeless para recuperar a página e MarkItDown para convertê-la. Uma chamada convert_stream transforma 11.021 caracteres de HTML em 2.973 caracteres de Markdown estruturado, pronto para um passo de embedding ou um pedido. Comece com o script acima, aponte para sua própria URL e passe o Markdown para seu modelo.

Comece com o plano gratuito do Scrapeless para recuperar suas próprias páginas, e cheque preços do Scrapeless ao dimensionar um trabalho recorrente.

FAQ

Q: O MarkItDown busca páginas da web por conta própria?

Não. O MarkItDown converte documentos que você fornece e não possui navegador ou desbloqueio, portanto, em uma página protegida, ele converteria uma página de desafios em vez do conteúdo. Combine-o com uma ferramenta de recuperação como o Scrapeless que retorna HTML renderizado e, em seguida, converta esse HTML.

Q: Como passo HTML extraído para o MarkItDown sem salvar um arquivo?

Use convert_stream com o HTML envolto em io.BytesIO e file_extension=".html", para que o MarkItDown analise os bytes em memória como HTML. Isso evita gravar a página extraída no disco apenas para lê-la de volta, e o Markdown está no text_content do resultado.

Q: Quais formatos o MarkItDown pode converter?

O MarkItDown aceita HTML, PDF, Word, PowerPoint, Excel, imagens e vários outros formatos, convertendo cada um para Markdown através da mesma interface. Para web scraping, a entrada relevante é HTML, mas o mesmo conversor lida com um PDF ou planilha extraída se seu pipeline coletar esses também.

Q: Devo usar o MarkItDown ou o trafilatura?

Use o MarkItDown quando você quiser que o documento inteiro seja convertido para Markdown estruturado, e o trafilatura quando você quiser apenas o artigo principal com navegação e rodapés removidos. Eles resolvem problemas diferentes: um é um conversor de formato, o outro é um extraidor de conteúdo principal.

Q: Por que converter para Markdown antes de chamar um modelo?

O Markdown mantém cabeçalhos, listas e links em uma forma compacta que os modelos de linguagem leem bem, enquanto o HTML bruto gasta tokens em tags e estilos que o modelo deve ignorar. Converter primeiro reduz o custo de tokens e fornece ao modelo uma estrutura mais limpa para trabalhar.