Cómo extraer un sitio web a Markdown: Una guía práctica
TL;DR
Convertir un sitio a Markdown es un pipeline de extracción, no una operación de eliminación de etiquetas: identificar las páginas canónicas, obtener la representación correcta, aislar el contenido principal, convertir la estructura y validar la salida.
Comience con una lista de URL delimitada o un mapa del sitio, respete las reglas de acceso y evite tratar la navegación, banners de cookies y recomendaciones como texto de artículo.
Preservar encabezados, enlaces, bloques de código, tablas, URL canónica y tiempo de observación; estos son a menudo más valiosos para un sistema de recuperación que el HTML decorativo.
Un pequeño pipeline de Python puede manejar páginas estáticas con httpx, Beautiful Soup y markdownify. Renderice JavaScript solo cuando el contenido objetivo esté ausente de la respuesta inicial.
Mida la fidelidad del contenido en páginas muestreadas antes de indexar todo el sitio; un Markdown de apariencia limpia aún puede omitir hechos esenciales o incluir la página incorrecta.
¿Qué significa raspar un sitio web a Markdown?
Raspar un sitio web a Markdown significa recolectar páginas autorizadas y convertir su contenido significativo en un formato de texto que preserve la estructura del documento. El resultado aún debería mostrar la jerarquía del título, párrafos, enlaces, listas, código y tablas. Un archivo lleno de texto aplanado es más fácil de producir pero más difícil de citar, fragmentar o revisar.
El trabajo tiene dos partes separadas. El descubrimiento determina qué URLs pertenecen al alcance. La extracción determina qué parte de cada página obtenida es el contenido real. Una biblioteca de conversión puede manejar la sintaxis de HTML a Markdown, pero no puede saber si un modal de boletín es parte del artículo o si una variante de producto fue seleccionada correctamente. La guía de descubrimiento de URL de sitios web cubre el primer problema; este tutorial se concentra en el segundo.
Para sitios grandes o pesados en JavaScript, Nstdata Crawl es una opción de adquisición para evaluar en páginas públicas representativas. Ya sea que use un servicio administrado o Python local, la salida aún necesita controles de alcance, procedencia y revisión humana.
Descubre Nstproxy Crawl - Empieza Tu Prueba Gratuita Hoy
Paso 1: Definir el contrato de origen y salida
Comience con una lista explícita de URLs que se le permite procesar. Un mapa del sitio es un punto de partida conveniente, pero filtrarlo por nombre de host y prefijo de ruta. Excluya URLs de inicio de sesión, carrito, búsqueda y URLs parametrizadas duplicadas a menos que sean parte de la tarea. La visión general del mapa del sitio de Google describe los mapas del sitio como sugerencias de descubrimiento, no garantías de que las páginas enumeradas sean válidas o completas.
Defina el registro de Markdown deseado antes de codificar. Un mínimo útil es source_url, final_url, title, fetched_at, content_hash y markdown. Si una página puede variar por localidad, cuenta u opción de producto, capture también ese contexto. No haga un nombre de archivo solo a partir de una URL en bruto; rutas largas, cadenas de consulta y colisiones hacen que eso sea poco fiable. Use una ruta estable más un hash o clave de base de datos.
Establezca un objetivo de calidad: por ejemplo, el Markdown debe retener cada H2, los ejemplos de código principales y las citas externas mientras excluye menús y navegación en el pie de página. Ese objetivo puede ser verificado en una muestra. Un alto conteo de caracteres no es una métrica de calidad si la mayoría de los caracteres son estándar.
Paso 2: Obtener una página con solicitudes delimitadas
El siguiente ejemplo utiliza Python 3, httpx, Beautiful Soup y markdownify. Instálelo con python -m pip install httpx beautifulsoup4 markdownify. El código solicita una única URL pública, establece un tiempo de espera, verifica el tipo de contenido y convierte el elemento main de la página cuando está disponible. La opción de volver a article o body es intencionalmente conservadora solo para una demostración; inspeccione el diseño de su sitio objetivo antes de ejecutarlo a gran escala.
from datetime import datetime, timezone
from hashlib import sha256
from urllib.parse import urlparse
import httpx
from bs4 import BeautifulSoup
from markdownify import markdownify as to_markdown
defpage_to_markdown(url:str)->dict[str,str]: parsed = urlparse(url)if parsed.scheme notin{"http","https"}:raise ValueError("Solo se permiten URLs HTTP(S)")with httpx.Client( timeout=15.0, follow_redirects=True, headers={"User-Agent":"ContentResearchExample/1.0"},)as client: response = client.get(url) response.raise_for_status() content_type = response.headers.get("content-type","").lower()if"text/html"notin content_type:raise ValueError(f"Se esperaba HTML, se obtuvo {content_type}") soup = BeautifulSoup(response.text,"html.parser")for node in soup.select("script, style, nav, footer, aside, form"): node.decompose() main = soup.select_one("main")or soup.select_one("article")or soup.body
if main isNone:raise ValueError("No se encontró un contenedor de contenido") title = soup.title.get_text(" ", strip=True)if soup.title else"Sin título"```python
markdown = to_markdown(str(main), heading_style="ATX").strip()iflen(markdown)<40:raise ValueError("El contenido extraído es inesperadamente corto")return{"source_url": url,"final_url":str(response.url),"title": title,"fetched_at": datetime.now(timezone.utc).isoformat(),"content_hash": sha256(markdown.encode()).hexdigest(),"markdown": markdown,}if __name__ =="__main__": record = page_to_markdown("https://example.com/")print(record["title"])print(record["markdown"][:300])
Este ejemplo intencionalmente no recursiona ni pasa por alto controles de acceso. El guardia len captura un resultado evidentemente vacío, no un resultado de contenido incorrecto. Pruebe en páginas con tablas, bloques de código y enlaces en línea antes de confiar en el convertidor. La especificación HTML's definición del elemento main es un interesante punto de partida semántico, pero muchos sitios no lo utilizan de manera consistente.
Paso 3: Mejorar la selección de contenido principal
El selector amplio en el ejemplo es solo una línea base. Un extractor de producción debería usar una regla específica del origen cuando el sitio tiene un envoltorio de artículo estable, y retroceder a un extractor de estilo de legibilidad cuando el diseño varía. Compare la página fuente y Markdown lado a lado. Busque introducciones que falten, encabezados duplicados, notas al pie en línea, tarjetas de publicaciones relacionadas y contenido inyectado debajo del artículo.
No elimine cada aside ciegamente cuando un aside editorial contenga una advertencia o definición. De manera similar, eliminar todas las tablas o imágenes puede eliminar la única representación de una especificación. Reemplace imágenes significativas por texto alternativo o un enlace cuando su uso posterior los necesite. Para ejemplos de código, verifique que la indentación y los cercos sobrevivan a la conversión. Para enlaces, prefiera URLs absolutas y mantenga el texto del enlace descriptivo; de lo contrario, las citas en una respuesta de recuperación pueden no llevar a ninguna parte.
La guía de métodos de extracción HTML compara enfoques de análisis. Para un corpus de recuperación, preservar la estructura generalmente importa más que maximizar la compresión de texto sin formato. Divida solo después de haber inspeccionado un documento fiel, y mantenga las rutas de encabezado con cada fragmento.
Paso 4: Manejar páginas renderizadas por JavaScript deliberadamente
Si la respuesta HTTP inicial contiene solo un contenedor de aplicación, el ejemplo de Python no puede extraer el artículo porque el texto llega más tarde a través de solicitudes del lado del cliente. Confirme esto viendo el cuerpo de la respuesta y el DOM renderizado por el navegador. Luego elija una API de fuente autorizada, un renderer de navegador u o un servicio de renderización gestionado. No renderice cada página por defecto: agrega latencia, costo y puntos de falla sin ayudar a las páginas estáticas.
La guía de Python para páginas renderizadas por JavaScript explica este diagnóstico con más detalle. Al usar un renderer, espere una señal específica de contenido en lugar de un sueño fijo. Una página puede estar visualmente completa mientras una tabla o lista de citas aún se estén cargando. Registre si el resultado provino del HTML fuente o del DOM renderizado porque la misma URL puede producir contenido diferente en cada camino.
Si el acceso requiere autenticación, use solo cuentas y contenido que esté explícitamente autorizado para procesar. No convierta una sesión del navegador en una licencia implícita para cosechar páginas privadas. Para páginas públicas, verifique robots.txt y términos del sitio; RFC 9309 define el protocolo de robots, no el conjunto completo de derechos legales para reutilizar contenido.
Paso 5: Validar y almacenar el Markdown
Cree una muestra de prueba que incluya los tipos de página más difíciles del sitio: páginas cortas, artículos largos, tablas, código, listas anidadas y páginas con muchas recomendaciones. Para cada muestra, compare encabezados principales, el primer y último párrafo, un hecho conocido, enlaces y cualquier bloque de código crítico. Marque una página como fallida cuando falte contenido importante, incluso si el Markdown es sintácticamente válido.
Elimine duplicados por URL canónica y hash de contenido, pero mantenga un historial de observación. Un cambio de hash puede significar una edición significativa o simplemente una tarjeta de recomendación rotativa. Compare la diferencia del contenido principal antes de reindexar. Almacene la fuente sin procesar o renderizada bajo una política de retención para que se puedan investigar errores de extracción. Si el contenido contiene datos personales, mantenga solo lo que el caso de uso necesita y propague la eliminación a copias e índices.
Para un flujo de trabajo de recuperación, almacene metadatos junto a cada archivo o fragmento de Markdown: URL, título, ruta de encabezado, tiempo de obtención, versión de la fuente y derechos de acceso. La guía de raspado web y RAG de LlamaIndex ofrece un contexto de ingestión más amplio. No etiquete una respuesta recuperada como “en vivo” simplemente porque el archivo Markdown fue creado con un raspador web una vez.
Errores comunes y cómo diagnosticarlos
Si cada archivo comienza con el mismo texto de navegación, el selector de contenido es demasiado amplio. Si los archivos están casi vacíos, inspeccione si la página es renderizada por JavaScript, bloqueada, redirigida o simplemente no es un artículo. Si los enlaces se vuelven relativos, resuélvalos contra la URL final obtenida antes de la conversión. Si una tabla se colapsa en un párrafo, elija un convertidor o un paso de post-procesamiento que preserve la semántica de la tabla y verifique el resultado manualmente.
Si aparecen páginas duplicadas, normalice solo los parámetros que son realmente irrelevantes; no combine variantes de productos o idiomas. Si faltan encabezados, verifique si fueron renderizados como elementos div con estilo en lugar de encabezados semánticos. Un pipeline fiable debería reportar estos como excepciones de tipo de página en lugar de silenciar la salida de un Markdown deficiente.
Conclusión
Una buena extracción de sitio web a Markdown es una transformación controlada con un conjunto de origen claro, un selector de contenido principal fiel, conversión estructural y verificación muestreada. Comience con algunas páginas públicas representativas, compare la fuente y la salida, y luego expanda el alcance de la URL. Preserve el origen para que cada pasaje en un sistema de búsqueda o RAG posterior pueda ser rastreado hasta una página y un momento de observación.
Pruebe un flujo de trabajo de página a Markdown
Si el análisis local no cubre sus tipos de página autorizados, evalúe Nstdata Crawl en un pequeño conjunto con encabezados y enlaces esperados conocidos. Mantenga el mismo contrato de validación y metadatos independientemente de la herramienta de adquisición.
P: ¿Puedo convertir un sitio completo a Markdown con una sola solicitud?
No. Una solicitud convierte una respuesta. Un flujo de trabajo en todo el sitio también necesita descubrimiento de URL acotado, obtención por página, deduplicación, programación y validación.
P: ¿Debería el Markdown incluir imágenes?
El Markdown debería retener imágenes significativas como enlaces o texto alternativo cuando transmiten información necesaria posteriormente. Las imágenes decorativas generalmente se pueden omitir, pero las gráficas y diagramas pueden requerir extracción o descripción separada.
P: ¿Es Markdown mejor que HTML para RAG?
Markdown es a menudo más fácil de inspeccionar y dividir, pero la fidelidad importa más que el formato. Si la conversión elimina tablas, citas o código, el HTML original o una representación más rica pueden ser mejores.
P: ¿Cómo sé si una página necesita renderización por JavaScript?
Compare la respuesta HTTP inicial con la página renderizada. Si el contenido requerido falta en la respuesta pero está presente después de la ejecución del lado del cliente, use una ruta de renderización o API autorizada y pruebe la finalización específica del contenido.
Lena Zhou
Oct. 13th 2026
Rastrea sitios web completos con una sola solicitud API
99,8% de éxito con renderizado JavaScript
Obtén datos limpios, listos para LLM, en múltiples formatos
Convierte cualquier sitio web en Markdown, HTML, JSON, enlaces, PDF y más, sin gestionar infraestructura de rastreo.
