Convierte HTML en Markdown limpio para RAG con la librería estándar de Python
Un script que extrae contenido principal, genera chunks estables y detecta cambios incrementales sin dependencias externas.
Se ha publicado un script en Python que transforma páginas web en fragmentos de Markdown limpios, específicamente diseñados para pipelines de RAG (retrieval-augmented generation) o índices de búsqueda. La herramienta utiliza únicamente la librería estándar de Python, evitando dependencias externas pesadas, y permite identificar qué secciones de una página han cambiado entre versiones para re-indexar solo lo necesario.
El proceso se divide en tres fases. Primero, el script analiza el HTML usando html.parser, construyendo un árbol de nodos simplificado. No es un parser completo de HTML5, por lo que no gestiona reglas implícitas de cierre de etiquetas, pero funciona bien para sitios documentales bien formados. Si el HTML es caótico, el autor recomienda usar html5lib o lxml para el parseo inicial.
En la segunda fase, se filtra el contenido. El script busca el elemento <main>, <article> o role="main" para aislar la información relevante, descartando navegación, scripts, estilos y formularios. Aquí es donde se adapata la limpieza a cada sitio: por ejemplo, elimina las clases específicas de Sphinx (como headerlink) que añaden anclas de pergamino a los encabezados, evitando que esos caracteres contaminen los nombres de las secciones.
La tercera fase es la renderización y segmentación. El contenido se convierte en CommonMark, con soporte para tablas de GitHub Flavored Markdown. Los enlaces relativos se convierten en absolutos con urljoin. A continuación, el texto se divide en chunks basados en la jerarquía de encabezados, asignando a cada uno un nombre estable compuesto por la ruta de sus títulos. Finalmente, al comparar dos versiones de la misma página, el script clasifica cada sección como añadida, eliminada, renombrada, cambiada, solo enlaces o invariable.
El ejemplo práctico incluye la documentación del módulo json de Python 3.13 y 3.14. Dado que docs.python.org restringe el acceso a versiones en fin de vida o de desarrollo en su robots.txt, se comparan estas dos versiones estables. Esto demuestra cómo actualizar un índice sin re-procesar la página completa, reduciendo la carga de cómputo y costes de inferencia al re-embedar solo los fragmentos modificados.
Para equipos que construyen sistemas de recuperación de información sobre documentación técnica, esta aproximación ofrece una alternativa ligera a las bibliotecas de scraping complejas. La ausencia de dependencias facilita la integración en contenedores mínimos o entornos de edge, y la lógica de diff incremental resuelve uno de los problemas operativos más comunes en RAG: la actualización eficiente de vectores.
