MarkItDown Web Scraping: Convierte Páginas a Markdown Listo para LLM

TL;DR:

• MarkItDown convierte una página HTML extraída en Markdown, manteniendo los encabezados, enlaces y listas que un modelo de lenguaje lee bien.
• La extracción te da HTML en memoria, por lo que la guía utiliza convert_stream con un BytesIO y una extensión explícita .html en lugar de una ruta de archivo.
• MarkItDown no tiene una capa de obtención que limpie bloques, por lo que Scrapeless recupera la página y MarkItDown la convierte.
• En la página de ejemplo, 11,021 caracteres de HTML se convierten en 2,973 caracteres de Markdown que comienza con un verdadero encabezado.
• MarkItDown convierte todo el documento a Markdown estructurado; utiliza trafilatura en su lugar cuando solo deseas el artículo principal con el contenido estándar eliminado.
• Comienza con el plan gratuito de Scrapeless y convierte tu primera página.

Los modelos de lenguaje leen Markdown mejor que HTML crudo. Markdown lleva la estructura que un modelo necesita, encabezados, listas y enlaces, sin la sopa de etiquetas, bloques de script y estilos en línea que llenan una página HTML. MarkItDown, el conversor de documento a Markdown de Microsoft, realiza esa conversión y maneja HTML, PDF, documentos de Office y más a través de una única interfaz. Lo que no hace es obtener la página, que es la mitad de un flujo de trabajo de extracción que tiene que suministrar.

Esta guía empareja los dos. La API de Extracción Universal de Scrapeless recupera la página y MarkItDown convierte el HTML devuelto a Markdown. Cada número a continuación proviene de una ejecución real contra una página pública.

Qué Hace MarkItDown

MarkItDown toma un documento y devuelve Markdown. Su razón de existir es la entrada de LLM: produce texto que mantiene la estructura en una forma eficiente en términos de tokens, siguiendo la ampliamente implementada especificación CommonMark para el Markdown que emite. El repositorio de MarkItDown enumera los formatos de entrada que acepta, que incluyen HTML, PDF, Word, PowerPoint y imágenes.

Lo que MarkItDown no es, es un extractor. No tiene navegador y ninguna forma de superar un desafío de acceso, por lo que convierte cualquier byte que le entregues. Obtener esos bytes de una página en vivo, a veces protegida, es un trabajo aparte.

Instalar

MarkItDown es una única instalación de pip.

pip install markitdown

Establece tu clave de Scrapeless en la terminal. Usa la clave real en tiempo de ejecución y mantén el marcador de posición fuera de tu fuente.

export SCRAPELESS_API_KEY="sk_your_key_here"

Convertir HTML Extraído a Markdown

La extracción devuelve una cadena HTML, no un archivo, por lo que el punto de entrada correcto es convert_stream. Envuelve el HTML en un BytesIO y pasa file_extension=".html" para que MarkItDown lo analice como HTML. El Markdown convertido está en el text_content del 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 crudos: {len(html)}")
print(f"caracteres markdown: {len(markdown)}")
print(f"comienza con encabezado: {markdown.lstrip().startswith('#')}")
print("--- primeras líneas de markdown ---")
for line in [line for line in markdown.splitlines() if line.strip()][:4]:
    print(line)

La ejecución informa los tamaños e imprime la parte superior del Markdown.

caracteres html crudos: 11021
caracteres markdown: 2973
comienza con encabezado: True
--- primeras líneas de markdown ---
# [Citas para Extraer](/)
[Iniciar sesión](/login)
“El mundo tal como lo hemos creado es un proceso de nuestro pensamiento. No puede ser cambiado sin cambiar nuestro pensamiento.”
por Albert Einstein

La salida comienza con un verdadero encabezado de Markdown y un enlace, y la primera cita de la página sigue. La estructura que puede usar el modelo sobrevive la conversión, y los 11,021 caracteres de HTML se reducen a 2,973 caracteres de Markdown.

Por Qué Markdown para un LLM

Markdown es el formato que la mayoría de los modelos de lenguaje están entrenados para leer, por lo que los encabezados se convierten en secciones, los enlaces permanecen legibles y las listas siguen siendo listas, todo en muchos menos tokens que el HTML original. Pasar HTML sin procesar en cambio gasta tokens en etiquetas y estilos en línea que el modelo tiene que ignorar, y entierra la estructura que ayuda al modelo a organizar el contenido. Convertir a Markdown primero es un paso económico que se ve recompensado en cada llamada posterior.

Donde se detiene MarkItDown

MarkItDown convierte; no recupera más allá de un bloque, razón por la cual esta guía lo empareja con una herramienta de recuperación. Dale a MarkItDown el HTML de una página protegida que se obtenga con un cliente simple y convertirá fielmente una página de desafío en Markdown. Scrapeless devuelve el HTML renderizado real, y MarkItDown convierte eso. Cuando un objetivo construye su contenido con JavaScript, establece js_render en True en la solicitud para que el HTML ya contenga el contenido; déjalo en False, como aquí, cuando la marca está renderizada en el servidor.

MarkItDown y trafilatura resuelven diferentes problemas. MarkItDown convierte todo el documento a Markdown estructurado, manteniendo la forma de la página. Trafilatura aísla el artículo principal y elimina el contenido habitual. Convierte con MarkItDown cuando deseas la página como Markdown; extrae con trafilatura cuando solo deseas el cuerpo del artículo.

Antes de ejecutar esto en un sitio, lee su robots.txt y términos. El Protocolo de Exclusión de Robots indica qué rutas un sitio pide a los clientes automáticos que eviten, y respetarlo mantiene sostenible un pipeline de conversión. Para el patrón más amplio, la guía sobre pipelines de contenido generado por IA muestra dónde encaja un paso de conversión como este.

¿Listo para convertir tus propias páginas? Crea una cuenta gratuita en Scrapeless y cambia la URL objetivo.

Conclusión

Alimentar a un modelo con Markdown en lugar de HTML es un pequeño cambio con un gran beneficio, y se necesitan dos herramientas: Scrapeless para recuperar la página y MarkItDown para convertirla. Una llamada a convert_stream convierte 11,021 caracteres de HTML en 2,973 caracteres de Markdown estructurado, listo para un paso de incrustación o un aviso. Comienza con el script anterior, apunta a tu propia URL y pasa el Markdown a tu modelo.

Comienza con el plan gratuito de Scrapeless para recuperar tus propias páginas y consulta los precios de Scrapeless cuando dimensionas un trabajo recurrente.

Preguntas frecuentes

P: ¿MarkItDown obtiene páginas web por sí mismo?

No. MarkItDown convierte documentos que le das y no tiene navegador ni desbloqueo, por lo que en una página protegida convertirá una página de desafío en lugar del contenido. Combínalo con una herramienta de recuperación como Scrapeless que devuelve HTML renderizado, y luego convierte ese HTML.

P: ¿Cómo paso HTML raspado a MarkItDown sin guardar un archivo?

Usa convert_stream con el HTML envuelto en io.BytesIO y file_extension=".html", de modo que MarkItDown analice los bytes en memoria como HTML. Esto evita escribir la página raspada en disco solo para leerla de nuevo, y el Markdown está en el text_content del resultado.

P: ¿Qué formatos puede convertir MarkItDown?

MarkItDown acepta HTML, PDF, Word, PowerPoint, Excel, imágenes y varios otros formatos, convirtiendo cada uno a Markdown a través de la misma interfaz. Para raspado web, la entrada relevante es HTML, pero el mismo convertidor maneja un PDF o una hoja de cálculo raspada si tu pipeline también recoge esos.

P: ¿Debo usar MarkItDown o trafilatura?

Usa MarkItDown cuando quieras convertir todo el documento a Markdown estructurado, y trafilatura cuando solo desees el artículo principal con la navegación y los pies de página eliminados. Resuelven problemas diferentes: uno es un convertidor de formato, el otro es un extractor de contenido principal.

P: ¿Por qué convertir a Markdown antes de llamar a un modelo?

Markdown mantiene los encabezados, listas y enlaces en una forma compacta que los modelos de lenguaje leen bien, mientras que el HTML sin procesar gasta tokens en etiquetas y estilos que el modelo debe ignorar. Convertir primero reduce el costo de tokens y proporciona al modelo una estructura más limpia con la que trabajar.