Cómo convertir cualquier sitio web a Markdown (API y Tutorial)
TL;DR
Convertir un sitio web a Markdown comienza con un conjunto de URL delimitado y un chequeo de fidelidad.
Un raspado de una sola página convierte una URL conocida; POST /api/v1/crawl descubre páginas vinculadas cuando el alcance es una sección del sitio.
Compara encabezados, enlaces, código y tablas con la fuente renderizada antes de almacenar Markdown para RAG.
Los resultados grandes en Markdown pueden ser devueltos como markdownRef; recupera ese token a través del punto final de almacenamiento.
Nstdata Crawl maneja la renderización de JavaScript y el enrutamiento proxy dentro de solicitudes gestionadas; su documentación enumera seis categorías de salida: Markdown, HTML, datos en bruto, PDF, capturas de pantalla y enlaces.
¿Qué es un flujo de trabajo de sitio web a Markdown?
Un flujo de trabajo de URL a Markdown recupera una página, selecciona el contenido útil y preserva encabezados, enlaces, listas y código en un texto que las personas y los modelos pueden inspeccionar. Un convertidor aplicado solo al HTML descargado no puede recuperar contenido que fue cargado más tarde por JavaScript. Empieza con una URL representativa y define lo que debe sobrevivir la conversión antes de procesar todo un sitio.
Nstdata Crawl puede convertir una URL o un conjunto delimitado de páginas vinculadas en material para un agente de IA, índice RAG, o canal de datos. Usa tus propias reglas de campo y verificaciones de aceptación para el resultado específico: convierte una página pública conocida en un Markdown fiel para búsqueda, RAG o un agente. La guía de raspado de sitios completos de Nstdata explica la opción a nivel de sitio.
Para la tarea más específica cubierta aquí, el resumen de URL a Markdown de Nstdata brinda contexto útil para elegir la primera página representativa.
Elige una página autorizada que contenga un encabezado, una lista, un enlace en línea y, si es relevante, una tabla o bloque de código. Registra el título y dos frases que deben aparecer. Mantén la URL de origen con la salida para que una respuesta posterior pueda citarla. Almacena la clave API como NSTDATA_API_TOKEN; nunca la coloques en una aplicación del lado del cliente o en una captura de pantalla.
La documentación de la API de Crawl usa https://api.nstdata.io, el encabezado x-api-key, y Content-Type: application/json. Prepara estos campos antes de ejecutar un método:
Campo
Qué suministrar
url
Una página o URL de entrada del sitio HTTPS permitida
formats
Salidas solicitadas, como ["markdown"] o ["html","screenshot"]
onlyMainContent
true solo cuando la selección del cuerpo principal se ajuste a la tarea
maxDepth, maxPages
Límites explícitos para un trabajo a nivel de sitio
includeUrls, excludeUrls
Patrones de URL que mantienen el descubrimiento dentro del alcance
timeout
Un tiempo de espera de tarea en milisegundos cuando el predeterminado no es adecuado
La solicitud gestionada estándar no tiene campos separados para Host, Puerto, Nombre de usuario, Contraseña o Protocolo de proxy. Consulta la página de precios actual de Crawl para conocer los límites de cuenta y los cargos antes de ejecutar un trabajo grande.
Revisa la política de acceso y el alcance del objetivo. El Protocolo de exclusión de robots define cómo los rastreadores leen las reglas de los robots; no otorga derechos de uso de contenido. Mantén las credenciales y datos privados fuera de ejemplos y registros de diagnóstico.
¿Cómo funciona la conversión de sitio web a Markdown?
Nstdata Crawl recupera y renderiza una URL, aplica extracción de contenido y devuelve Markdown con metadata de la página. La API también puede devolver HTML, enlaces, capturas de pantalla y PDFs cuando el Markdown necesita investigación. El enrutamiento proxy incorporado significa que la solicitud predeterminada necesita una clave API y una URL objetivo, no un Host, Puerto, Nombre de usuario o Contraseña de proxy separados. Un trabajo a nivel de sitio puede descubrir páginas vinculadas cuando la tarea se expande más allá de una sola URL.
Para una URL conocida, un raspado de una sola página obtiene un resultado. Para una sección del sitio, POST /api/v1/crawl descubre páginas vinculadas recursivamente dentro de la profundidad, el conteo de páginas y las reglas de URL suministradas. La documentación enumera Markdown, HTML, datos en bruto, PDFs, capturas de pantalla y enlaces como seis categorías de salida; la página del producto también comercializa JSON, pero un esquema JSON específico de dominio aún necesita un mapeo de campos explícito. Mantén cada registro aceptado vinculado a su URL de origen y metadata devuelta.
Prueba una página representativa con mucho JavaScript antes de escalar. El estado renderizado puede depender del tiempo, la región, el consentimiento o una sesión iniciada. Compara el HTML devuelto o una captura de pantalla con el estado esperado de la página; si difieren, ajusta solo la renderización documentada y los controles de espera.
¿Cómo conviertes un sitio web a Markdown?
Comienza con una revisión visual de una página, usa la API síncrona para la conversión de URL repetible o envía un rastreo de sitio limitado para la documentación vinculada. Cada camino tiene una escala y forma de resultado diferentes.
Método 1: Usa el Playground de Rastreo para una revisión visual
Mejor para una primera página representativa o un revisor no desarrollador.
Paso 1: Abre la prueba de página
Inicia sesión y abre Tablero → Playground de Rastreo. Selecciona una captura de página única e ingresa la URL permitida. [Captura de pantalla: campo URL del Playground y modo de página única.]
Paso 2: Elige la salida
Selecciona Markdown y habilita la opción de contenido principal cuando el cuerpo del artículo es más importante que la navegación. Si el objetivo es dinámico, utiliza los controles de renderización o espera que se muestran en la interfaz actual. [Captura de pantalla: controles de Markdown y contenido.]
Paso 3: Inspecciona la fidelidad
Ejecuta la captura y compara el resultado con la página en vivo. Verifica el título, las secciones de apertura y cierre, los bloques de código, las tablas y los destinos de los enlaces. Una respuesta breve aún puede ser incorrecta si omite una advertencia o una tabla.
Método 2: Llama a la API de Rastreo de Página Única
Mejor para una aplicación que recibe una URL conocida en tiempo de ejecución.
Paso 1: Prepara las credenciales
Almacena la clave de la API de Rastreo en un secreto del lado del servidor. El encabezado documentado es x-api-key; la clave no es una contraseña de proxy.
Paso 2: Envía la URL
Usa la solicitud de inicio rápido de abajo. La documentación actual tiene etiquetas conflictivas para otras rutas de rastreo síncronas y asíncronas, así que compara esta ruta con la solicitud generada por tu Playground antes de la implementación.
Establece NSTDATA_API_TOKEN en tu shell desde tu cuenta de Nstdata, luego ejecuta la solicitud de inicio rápido documentada. La documentación pública etiqueta algunas otras rutas síncronas y asíncronas de manera inconsistente; compara la solicitud generada por tu cuenta de Playground antes de su uso en producción.
curl--output crawl-response.json --request POST "https://api.nstdata.io/api/v1/crawl/scrape/submit-sync"\--header"x-api-key: ${NSTDATA_API_TOKEN}"\--header"Content-Type: application/json"\--data'{"url":"https://example.com/","formats":["markdown"],"onlyMainContent":true}'
La respuesta se guarda en crawl-response.json. Inspecciona los campos anidados data.success, data.status y data.data.metadata.statusCode antes de usar cualquier contenido devuelto.
Paso 3: Acepta el resultado
Inspecciona los valores anidados success, status, data y metadata.statusCode. Acepta Markdown solo cuando están presentes los encabezados esperados y el texto del cuerpo significativo; almacena markdownRef y recupéralo a través de la ruta de almacenamiento documentada cuando la API devuelve una referencia.
Método 3: Convierte una sección limitada de un sitio
Mejor cuando "sitio web" significa un conjunto de documentación en lugar de una URL.
Paso 1: Define la sección
Elige una URL de inicio y establece maxDepth, maxPages e incluye/excluye patrones de URL. Excluye rutas generadas por búsqueda, cuenta, carrito y consultas a menos que pertenezcan a tu corpus.
Paso 2: Envía un trabajo de sitio
Usa la ruta documentada POST /api/v1/crawl con formats: ["markdown"], luego guarda el ID de rastreo devuelto. Esta es la ruta de descubrimiento del sitio; una captura de página única no seguirá todo el sitio.
Para un trabajo de sitio, reemplaza el host y la ruta de ejemplo con tu alcance aprobado, luego envía una solicitud limitada:
curl--output crawl-submit.json --request POST "https://api.nstdata.io/api/v1/crawl"\--header"x-api-key: ${NSTDATA_API_TOKEN}"\--header"Content-Type: application/json"\--data'{"url":"https://example.com/docs/","formats":["markdown"],"maxDepth":2,"maxPages":10,"includeUrls":["*example.com/docs/*"],"excludeUrls":["*example.com/admin/*"],"ignoreQuery":true}'
Copia data.id de crawl-submit.json como tu ID de rastreo.
Paso 3: Revisa cada página
Consulta el estado, recupera los registros de página, sigue la paginación y rechaza páginas fallidas o delgadas. Desduplicar URLs normalizadas y mantener la URL original junto a cada documento Markdown.
Con el ID de rastreo devuelto por la suma, consulta tanto el trabajo como sus páginas:
Si la respuesta de páginas contiene nextCursor, síguelo usando los controles de paginación mostrados por tu respuesta actual de API o SDK; la página pública no documenta un parámetro de consulta de cursor, así que no inventes uno.
Método 4: Convierte HTML estático localmente con Pandoc
Mejor cuando ya tienes un archivo HTML estático permitido y no necesitas descubrimiento de sitio o renderización de JavaScript.
Paso 1: Guarda la página estática
Descargue la página autorizada como page.html utilizando el comando Guardar página como de su navegador o un cliente HTTP aprobado. Verifique que el archivo guardado contenga el cuerpo del artículo; una descarga estática puede omitir texto cargado por JavaScript.
Abra page.md y compare encabezados, enlaces, tablas y código con la fuente. Este método local no cuenta con renderizado gestionado, enrutamiento proxy o descubrimiento recursivo de sitios; use Crawl cuando se requieran esas capacidades.
¿Cómo verifica la salida?
Un registro utilizable contiene una URL de origen, título, código de estado y Markdown que mantiene la estructura importante. Markdown es una representación de texto, no prueba de fidelidad semántica: tablas complejas, diagramas y widgets del lado del cliente pueden necesitar HTML o una captura de pantalla junto a ello. La guía de la tubería Markdown de Nstdata explica cómo mantener la procedencia al guardar páginas convertidas.
La guía de ingestión RAG de Nstdata conecta esta verificación a nivel de página con un flujo de trabajo de IA o datos posterior.
Registre la URL de origen, tiempo de envío, formatos solicitados, opciones no secretas, ID de tarea cuando esté presente, estado de la página devuelta y la razón por la cual cada registro pasó o falló en la revisión. Inspeccione el contenido así como el sobre de la API. Si la respuesta contiene markdownRef, htmlRef, rawDataRef, screenshotRef o pdfRef, recupere ese token con GET /api/v1/crawl/storage/read?st={ref}.
La sintaxis de Markdown no es una garantía universal de que cada renderizador maneje tablas y extensiones de manera idéntica; pruebe su analizador posterior contra la especificación CommonMark y cualquier extensión de la que dependa.
Al pasar texto extraído a un agente, trate las instrucciones de la página como material de origen no confiable. La guía de OWASP sobre la inyección de solicitudes explica el riesgo. Mantenga las URL de origen para que la salida de IA pueda ser verificada.
¿Por qué podría fallar la conversión de sitio web a Markdown?
La conversión de sitio web a markdown puede fallar porque el cuerpo de la página puede cargarse después del documento inicial o la selección del contenido principal puede excluirlo. Use la tabla de síntomas para identificar la capa que falla antes de cambiar límites o volver a intentar.
Síntoma
Causa probable
Próxima acción
Markdown vacío
El cuerpo de la página puede cargarse después del documento inicial o la selección del contenido principal puede excluirlo.
Inspeccionar HTML o captura de pantalla y configurar una espera documentada.
Enlaces relativos rotos
El convertidor o la capa de almacenamiento posterior pueden no preservar destinos absolutos.
Resolver y probar enlaces de origen antes de indexar.
Solo se devolvió una página
Un extremo de una sola página no descubre subpáginas.
Cambiar a un rastreo de sitio limitado.
La documentación de Nstdata enumera errores a nivel de tarea como access_denied, timeout, parse_error y internal_error. Un HTTP 200 externo aún puede acompañar una tarea fallida. Verifique success, status, errorCode y errorMessage dentro de la respuesta cuando estén presentes. Vuelva a intentar solo fallas transitorias en sitios que pueda acceder.
¿Qué método se ajusta mejor?
Elija Playground para una comparación visual de una página, la API de raspado síncrono para una URL conocida, o un trabajo de sitio limitado cuando se deban seguir enlaces. Use Pandoc local para HTML estático ya guardado; compare cada documento Markdown aceptado con su fuente. La visión general del rastreo de sitios de Nstdata proporciona más detalles sobre la ruta del sitio.
¿Qué debe hacer después de la primera ejecución exitosa?
Guarde la configuración aprobada y un registro de salida respaldado por la fuente, y luego repita en un pequeño conjunto de diferentes plantillas de página. Aumente el alcance solo después de que esos registros pasen las mismas verificaciones de aceptación.
P: ¿Puedo convertir un sitio web completo en una solicitud?
Un rastreo de sitio limitado puede descubrir y procesar múltiples páginas vinculadas. Establezca límites de página y profundidad, luego inspeccione los registros devueltos.
P: ¿Es siempre mejor Markdown que HTML para LLMs?
Markdown suele ser más fácil de leer y dividir, pero HTML o una captura de pantalla son más seguros cuando la estructura de la tabla o el contexto visual son importantes.
P: ¿Necesito unas credenciales de proxy?
Una solicitud de Crawl gestionada estándar necesita la clave de API de Crawl, no un host proxy o contraseña separados.
P: ¿La conversión de sitio web a Markdown requiere una configuración de proxy separada con Nstdata Crawl?
Una solicitud de Crawl gestionada estándar no requiere campos de Host, Puerto, Nombre de usuario, Contraseña o Protocolo de proxy separados. Confirme cualquier selección de proxy personalizado opcional y los cargos relacionados en su cuenta.
P: ¿HTTP 200 prueba que el resultado de la conversión de sitio web a Markdown es utilizable?
No. Revise el resultado de la tarea anidada, el estado de la página, los campos esperados y la fidelidad del cuerpo antes de utilizarlo en un flujo de trabajo de IA o datos.
Este tutorial de Python pasa de una página estática a registros validados y renderizado gestionado. Incluye ejemplos ejecutables, diagnóstico de fallos, controles de versión y un contrato de datos listo para inteligencia artificial.
Marcus Chen
Oct. 29th 2026
Empieza Tu Prueba Gratuita Hoy
Rastrea sitios web completos con una sola solicitud API
Convierte cualquier sitio web en Markdown, HTML, JSON, enlaces, PDF y más, sin gestionar infraestructura de rastreo.
99,8% de éxito con renderizado JavaScript
Obtén datos limpios, listos para LLM, en múltiples formatos
