Archivos de configuración
Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →
Un archivo de configuración de DocSearch tiene este aspecto:
{
"index_name": "example",
"start_urls": ["https://www.example.com/docs"],
"selectors": {
"lvl0": "#content header h1",
"lvl1": "#content article h1",
"lvl2": "#content section h3",
"lvl3": "#content section h4",
"lvl4": "#content section h5",
"lvl5": "#content section h6",
"text": "#content header p,#content section p,#content section ol"
}
}
index_name
Este es el nombre del índice de Algolia donde se insertarán tus registros. La apiKey que compartiremos contigo está restringida para trabajar con este índice y es una clave de solo búsqueda.
Al usar el crawler gratuito de DocSearch, el indexName siempre será el nombre del archivo de configuración. Si ejecutas DocSearch por tu cuenta, puedes usar cualquier nombre.
{
"index_name": "example"
}
Cuando el scraper de DocSearch se ejecuta, crea un índice temporal. Al completar el scraping, mueve ese índice al nombre especificado por index_name (reemplazando el índice existente).
Por defecto, el nombre del índice temporal es el valor de index_name + _tmp.
Para usar un nombre diferente, establece la variable de entorno INDEX_NAME_TMP con otro valor. Esta variable puede configurarse en el archivo .env junto a APPLICATION_ID y API_KEY.
start_urls
Este array contiene la lista de URLs iniciales para rastrear tu sitio. El crawler seguirá recursivamente los enlaces (<a>) desde estas páginas. No seguirá enlaces de otros dominios ni aquellos que coincidan con stop_urls.
{
"start_urls": ["https://www.example.com/docs"]
}
selectors_key, personaliza tus selectores
Puedes definir conjuntos de selectores más específicos según la URL usando el parámetro selectors_key en tus start_urls.
{
"start_urls": [
{
"url": "http://www.example.com/docs/faq/",
"selectors_key": "faq"
},
{
"url": "http://www.example.com/docs/"
}
],
[…],
"selectors": {
"default": {
"lvl0": ".docs h1",
"lvl1": ".docs h2",
"lvl2": ".docs h3",
"lvl3": ".docs h4",
"lvl4": ".docs h5",
"text": ".docs p, .docs li"
},
"faq": {
"lvl0": ".faq h1",
"lvl1": ".faq h2",
"lvl2": ".faq h3",
"lvl3": ".faq h4",
"lvl4": ".faq h5",
"text": ".faq p, .faq li"
}
}
}
El scraper itera sobre los elementos de start_urls para encontrar el primer coincidente. Solo se aplica el primer conjunto que coincide.
Considerando la URL http://www.example.com/en/api/ con la configuración:
{
"start_urls": [
{
"url": "http://www.example.com/doc/",
"selectors_key": "doc"
},
{
"url": "http://www.example.com/doc/faq/",
"selectors_key": "faq"
},
[…],
]
}
Solo se aplicará el conjunto de selectores para doc. La configuración correcta debe construirse al revés (como se describió inicialmente).
Si un elemento de start_urls no define selectors_key, se usará el conjunto default. No olvides configurar este conjunto de respaldo.
Uso de expresiones regulares
Las opciones start_urls y stop_urls permiten usar expresiones regulares para patrones complejos. Puedes definir un array de regex u objetos. Cada objeto debe incluir al menos una clave url que apunte a una página accesible.
Si defines tu regex como objeto, puedes añadir una clave variables que se inyectará en tu patrón de URL. Este ejemplo aclara la funcionalidad:
{
"start_urls": [
{
"url": "http://www.example.com/docs/(?P<lang>.*?)/(?P<version>.*?)/",
"variables": {
"lang": ["en", "fr"],
"version": ["latest", "3.3", "3.2"]
}
}
]
}
El efecto secundario beneficioso es que cada registro extraído de páginas como http://www.example.com/docs/en/latest tendrá atributos lang: en y version: latest. Esto permite filtrar con estos facetFilters.
Este ejemplo muestra cómo la interfaz filtra resultados por idioma y versión específicos.
docsearch({
[…],
algoliaOptions: {
'facetFilters': ["lang:en", "version:latest"]
},
[…],
});
Uso de etiquetas personalizadas
Puedes aplicar etiquetas personalizadas a páginas sin usar regex. Añade la lista de etiquetas en la clave tags. Estas etiquetas se convertirán automáticamente en facetas en Algolia, permitiendo filtrar por sus valores.
{
"start_urls": [
{
"url": "http://www.example.com/docs/concepts/",
"tags": ["concepts", "terminology"]
}
]
}
Desde el fragmento JS:
docsearch({
[…],
algoliaOptions: {
'facetFilters': ["tags:concepts"]
},
});
Uso de Page Rank
Para priorizar ciertas páginas. Este parámetro aumenta el peso de los registros generados desde la página. Las páginas con mayor page_rank aparecerán antes que aquellas con menor page_rank. Puedes usar cualquier valor numérico, incluidos negativos.
{
"start_urls": [
{
"url": "http://www.example.com/docs/concepts/",
"page_rank": 5
},
{
"url": "http://www.example.com/docs/contributors/",
"page_rank": 1
}
]
}
En este ejemplo, los registros de la página Conceptos tendrán mayor prioridad que los de Colaboradores.
Uso de selectores personalizados por página
Si el maquetado de tu sitio web varía tanto entre páginas que no puedes usar selectores genéricos, puedes organizar tus selectores en espacios de nombres y especificar qué conjunto aplicar en páginas específicas.
{
"start_urls": [
"http://www.example.com/docs/",
{
"url": "http://www.example.com/docs/concepts/",
"selectors_key": "concepts"
},
{
"url": "http://www.example.com/docs/contributors/",
"selectors_key": "contributors"
}
],
"selectors": {
"default": {
"lvl0": ".main h1",
"lvl1": ".main h2",
"lvl2": ".main h3",
"lvl3": ".main h4",
"lvl4": ".main h5",
"text": ".main p"
},
"concepts": {
"lvl0": ".header h2",
"lvl1": ".main h1.title",
"lvl2": ".main h2.title",
"lvl3": ".main h3.title",
"lvl4": ".main h5.title",
"text": ".main p"
},
"contributors": {
"lvl0": ".main h1",
"lvl1": ".contributors .name",
"lvl2": ".contributors .title",
"text": ".contributors .description"
}
}
}
Aquí, todas las páginas de documentación usarán los selectores definidos en selectors.default, mientras que las páginas bajo ./concepts usarán selectors.concepts y aquellas bajo ./contributors usarán selectors.contributors.
selectors
Este objeto contiene todos los selectores CSS que crearán la jerarquía de registros. Puede incluir hasta 6 niveles (lvl0, lvl1, lvl2, lvl3, lvl4, lvl5) y text.
Una configuración típica sería usar el title de la página o h1 como lvl0, h2 como lvl1, h3 como lvl2 y p como text, pero esto depende totalmente del maquetado.
La clave text es obligatoria, pero recomendamos configurar también lvl0, lvl1 y lvl2 para lograr una profundidad de relevancia adecuada.
{
"selectors": {
"lvl0": "#content header h1",
"lvl1": "#content article h1",
"lvl2": "#content section h3",
"lvl3": "#content section h4",
"lvl4": "#content section h5",
"lvl5": "#content section h6",
"text": "#content header p,#content section p,#content section ol"
}
}
Los selectores pueden pasarse como strings u objetos con una clave selector. Se pueden configurar otras claves especiales como se documenta abajo.
{
"selectors": {
"lvl0": {
"selector": "#content header h1"
}
}
}
Usar selectores globales
El método predeterminado para extraer contenido mediante selectores es leer el maquetado HTML de arriba hacia abajo. Esto funciona bien con contenido semiestructurado, como jerarquías de encabezados. Fallará cuando la información relevante no sea parte del mismo flujo, por ejemplo si el título no está en un encabezado o barra lateral.
Por eso puedes marcar un selector como global, significando que coincidirá en toda la página y será idéntico para todos los registros extraídos de ella.
{
"selectors": {
"lvl0": {
"selector": "#content header h1",
"global": true
}
}
}
No recomendamos que los selectores text sean globales.
Establecer un valor predeterminado
Si un selector no coincide con ningún elemento válido en la página, puedes definir un default_value como alternativa.
{
"selectors": {
"lvl0": {
"selector": "#content header h1",
"default_value": "Documentation"
}
}
}
Eliminar caracteres innecesarios
Alguna documentación añade caracteres especiales a los encabezados, como # o ›. Estos tienen valor estilístico pero no semántico, y no deberían indexarse en los resultados de búsqueda.
Puedes definir una lista de caracteres a excluir del valor indexado final usando la clave strip_chars.
{
"selectors": {
"lvl0": {
"selector": "#content header h1",
"strip_chars": "#›"
}
}
}
Nota que también puedes definir strip_chars directamente en la raíz de la configuración, aplicándose entonces a todos los selectores.
{
"strip_chars": "#›"
}
Objetivar elementos usando XPath en lugar de CSS
Los selectores CSS son claros y concisos para objetivar elementos, pero tienen limitaciones. Por ejemplo, no puedes navegar hacia arriba en la cascada con CSS.
Si necesitas un mecanismo más potente, puedes escribir selectores usando XPath configurando type: xpath.
Este ejemplo buscará un li.chapter.active.done, luego subirá dos niveles en el DOM hasta encontrar un a. El contenido de este a se usará como valor del selector lvl0.
{
"selectors": {
"lvl0": {
"selector": "//li[@class=\"chapter active done\"]/../../a",
"type": "xpath",
"global": true
}
}
}
Los selectores XPath pueden ser difíciles de leer. Te recomendamos probarlos primero en tu navegador para verificar que coincidan con lo esperado.
custom_settings Opcional
Esta clave permite sobrescribir la configuración de tu índice Algolia. No recomendamos modificarla pues los valores predeterminados funcionan para la mayoría de sitios web.
custom_settings.separatorsToIndex Opcional
Un caso de uso sería configurar separatorsToIndex. Por defecto Algolia trata los caracteres especiales como separadores de palabras. En contextos como nombres de métodos, quizá quieras que _, / o # conserven su significado.
{
"custom_settings": {
"separatorsToIndex": "_/"
}
}
Consulta la documentación de Algolia para más información sobre su configuración.
custom_settings.synonyms Opcional
custom_settings puede incluir una clave synonyms que es un array de sinónimos. Cada elemento es un array de sinónimos de una palabra. Estas palabras son intercambiables.
Por ejemplo:
"custom_settings": {
"synonyms": [
[
"js",
"javascript"
],
[
"es6",
"ECMAScript6",
"ECMAScript2015"
]
]
},
Nota: Puedes usar sinónimos avanzados con Algolia. Nuestro scraper solo admite sinónimos regulares de una palabra.
scrape_start_urls Opcional
Por defecto, el crawler extraerá contenido de las páginas definidas en start_urls. Si no tienes contenido valioso en tus starts_urls o es duplicado de otra página, debes establecer esto en false.
{
"scrape_start_urls": false
}
selectors_exclude Opcional
Espera un array de selectores CSS. Cualquier elemento que coincida con estos selectores será eliminado de la página antes de extraer datos.
Útil para eliminar tablas de contenido, barras laterales o pies de página, facilitando la escritura de otros selectores.
{
"selectors_exclude": [".footer", "ul.deprecated"]
}
stop_urls Opcional
Array de strings o expresiones regulares. Cuando el crawler intenta visitar un enlace, verifica si coincide con este array. Si coincide, no sigue el enlace. Sirve para restringir páginas que el crawler debe visitar.
Nota: Suele usarse para evitar contenido duplicado, añadiendo http://www.example.com/docs/index.html si ya tienes http://www.example.com/docs/ como start_urls.
{
"stop_urls": ["https://www.example.com/docs/index.html", "license.html"]
}
min_indexed_level Opcional
Valor predeterminado: 0. Al incrementarlo, puedes evitar indexar registros sin suficientes coincidencias lvlX. Ej: con min_indexed_level: 2, el scraper indexa solo registros que tengan al menos lvl0, lvl1 y lvl2 definidos. Más detalles sobre esta estrategia aquí.
Útil cuando tu documentación tiene páginas que comparten el mismo lvl0 y lvl1. En ese caso, no querrás indexar todos los registros compartidos, sino mantener contenido diferenciado por página.
{
"min_indexed_level": 2
}
only_content_level Opcional
Cuando only_content_level es true, el crawler no creará registros para los selectores lvlX.
Si se usa, min_indexed_level se ignora.
{
"only_content_level": true
}
nb_hits Especial
Número de registros extraídos e indexados por DocSearch. Verificamos internamente esta clave para detectar picos/caídas inesperados que revelen configuraciones erróneas.
nb_hits se actualiza automáticamente en cada ejecución. Si es una terminal TTY, DocSearch pedirá confirmación antes de actualizar. Para evitar esto, establece la variable de entorno UPDATE_NB_HITS en true (activar) o false (desactivar). Esta variable puede configurarse en el archivo .env junto a APPLICATION_ID y API_KEY.
No necesitas editar este campo. Lo documentamos por si te preguntabas su propósito.
Sitemaps
Si tu sitio tiene un archivo sitemap.xml, puedes informar a DocSearch para que lo use al definir qué páginas rastrear.
sitemap_urls Opcional
Puedes pasar un array de URLs apuntando a tus sitemap(s). Si se establece, DocSearch leerá URLs del sitemap en lugar de seguir cada enlace de tus starts_urls.
{
"sitemap_urls": ["http://www.example.com/docs/sitemap.xml"]
}
Debes definir explícitamente este parámetro; nuestro scraper no sigue robots.txt.
sitemap_alternate_links Opcional
Los sitemaps pueden contener enlaces alternativos para URL. Son otras versiones de la misma página, en un idioma diferente o con una URL distinta. Por defecto, DocSearch ignorará esas URL.
Establece esto en true si deseas que también se rastreen esas otras versiones.
{
"sitemap_urls": ["http://www.example.com/docs/sitemap.xml"],
"sitemap_alternate_links": true
}
Con la configuración anterior y el sitemap.xml que se muestra a continuación, se rastrearán tanto http://www.example.com/docs/ como http://www.example.com/docs/de/.
<url>
<loc>http://www.example.com/docs/</loc>
<xhtml:link rel="alternate" hreflang="de" href="http://www.example.com/de/"/>
</url>
Renderizado JavaScript
Por defecto, DocSearch espera que los sitios web tengan renderizado del lado del servidor, lo que significa que el código fuente HTML es devuelto directamente por el servidor. Si tu contenido se genera en el front-end, debes indicar a DocSearch que emule un navegador mediante Selenium.
Como el rastreo del lado del cliente es mucho más lento que el del lado del servidor, te recomendamos encarecidamente que actualices tu sitio web para habilitar el renderizado del lado del servidor.
js_render Opcional
Establece este valor en true si tu sitio web requiere renderizado del lado del cliente. Esto hará que DocSearch lance un proxy de Selenium para obtener todas tus páginas web.
{
"js_render": true
}
js_wait Opcional
Si tu sitio web tarda en cargar, puedes usar js_wait para indicar a DocSearch que espere una cantidad específica de tiempo (en segundos) antes de extraer el contenido.
Ten en cuenta que esta opción puede afectar significativamente el tiempo requerido para rastrear tu sitio web, y te recomendamos habilitar el renderizado del lado del servidor en su lugar.
Esta opción no tiene efecto si js_render está establecido en false.
{
"js_render": true,
"js_wait": 2
}
use_anchors Opcional
Los sitios web que usan renderizado del lado del cliente a menudo no utilizan URL completas, sino que aprovechan el hash de la URL (la parte después del #).
Si tu sitio web utiliza este tipo de URL, debes establecer use_anchors en true para que DocSearch indexe todo tu contenido.
{
"js_render": true,
"use_anchors": true
}
user_agent Opcional
Puedes sobrescribir el agente de usuario utilizado para rastrear tu sitio web. Por defecto, este valor es:
Algolia DocSearch Crawler
Sin embargo, si el rastreo de tu sitio web requiere emulación de navegador (es decir, js_render=true), nuestro user_agent es:
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) HeadlessChrome/71.0.3578.98 Safari/537.36
Para sobrescribirlo, desde la configuración:
{
"user_agent": "Custom Bot"
}