Configuración requerida

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Esta sección, respaldada por los detalles sobre cómo construimos un índice de DocSearch, te brinda las mejores prácticas para optimizar nuestro rastreo. Adoptar esta especificación es necesario para permitir que nuestro crawler construya la mejor experiencia desde tu sitio web. Necesitarás actualizar tu sitio web y seguir estas reglas.

Nota: Si tu sitio web se genera con una de nuestras herramientas compatibles, no necesitas realizar cambios ya que cumple con nuestros requisitos.

Ejemplo de configuración genérica

{
  "index_name": "example",
  "start_urls": ["https://www.example.com/doc/"],
  "sitemap_urls": ["https://www.example.com/sitemap.xml"],
  "stop_urls": [],
  "selectors": {
    "lvl0": {
      "selector": ".DocSearch-lvl0",
      "global": true,
      "default_value": "Documentation"
    },
    "lvl1": {
      "selector": ".DocSearch-lvl1",
      "global": true,
      "default_value": "Chapter"
    },
    "lvl2": ".DocSearch-content .DocSearch-lvl2",
    "lvl3": ".DocSearch-content .DocSearch-lvl3",
    "lvl4": ".DocSearch-content .DocSearch-lvl4",
    "lvl5": ".DocSearch-content .DocSearch-lvl5",
    "lvl6": ".DocSearch-content .DocSearch-lvl6",
    "text": ".DocSearch-content p, .DocSearch-content li"
  },
  "custom_settings": {
    "attributesForFaceting": ["language", "version"]
  },
  "nb_hits": "OUTPUT OF THE CRAWL"
}

Visión general de un diseño claro

Un sitio web que implemente estas mejores prácticas lucirá simple y cristalino. Puede tener el siguiente aspecto:

El elemento azul principal será tu contenedor .DocSearch-content. Más detalles en las siguientes pautas.

Usa las clases adecuadas como selectores

Puedes añadir clases estáticas específicas para ayudarnos a identificar el rol de tu contenido. Estas clases no deben implicar cambios de estilo. Estas clases dedicadas nos ayudarán a crear una excelente experiencia de aprendizaje mientras escribes en tu documentación.

• Añade una clase estática DocSearch-content al contenedor principal de tu contenido textual. Normalmente, esta etiqueta es un elemento HTML <main> o <article>.

• Todo elemento lvl buscable fuera de este contenedor principal (por ejemplo en una barra lateral) debe ser un selector global. Serán recogidos globalmente e inyectados en cada registro construido desde tu página. Importante: el valor del nivel es crucial y cada elemento coincidente debe tener un nivel creciente en el flujo HTML. Un nivel X (para lvlX) debe aparecer después de un nivel Y cuando X > Y.

• Los selectores lvlX deben usar etiquetas de título estándar como h1, h2, h3, etc. También puedes usar clases estáticas. Establece un atributo id o name único en estos elementos como se detalla a continuación.

• Cada elemento DOM que coincida con los selectores lvlX debe tener un atributo id o name único. Esto ayuda a que la redirección se desplace directamente al lugar exacto de los elementos coincidentes. Estos atributos definen el anclaje correcto a utilizar.

• Cada elemento textual (selector text) debe estar envuelto en una etiqueta <p> o <li>. Este contenido debe ser atómico y dividido en pequeñas entidades. Evita anidar elementos coincidentes dentro de otros para prevenir duplicados.

• Mantén la coherencia y recuerda que necesitamos consistencia a lo largo del flujo HTML como se muestra aquí.

Introducir información global mediante metaetiquetas

Nuestro crawler extrae automáticamente información de las metaetiquetas específicas de DocSearch:

<meta name="docsearch:language" content="en" />
<meta name="docsearch:version" content="1.0.0" />

El rastreo añade el valor content de estas etiquetas meta a todos los registros extraídos de la página. El name de las metaetiquetas debe seguir el patrón docsearch:$NAME. $NAME es el nombre del atributo establecido para todos los registros.

Puedes convertir estos atributos en facetFilters para filtrarlos desde la interfaz. Deberás configurar el parámetro attributesForFaceting del índice de Algolia mediante un PR en tu configuración asociada usando el ajuste custom_settings de DocSearch.

"custom_settings": {
  "attributesForFaceting": ["language", "version"]
}

Esto te permite filtrar por el valor de estas metaetiquetas. El siguiente ejemplo muestra cómo actualizar el fragmento JavaScript para recuperar registros de estas páginas.

docsearch({
  […],
  algoliaOptions: {
    'facetFilters': ["language:en", "version:1.0.0"]
  },
  […],
});

La metaetiqueta docsearch:version puede ser un conjunto de tokens separados por comas, cada uno relevante para la página. Estos tokens deben cumplir con la especificación SemVer o contener solo caracteres alfanuméricos (ej. latest, next, etc.). Como filtros de faceta, estos tokens son insensibles a mayúsculas/minúsculas.

Por ejemplo, todos los registros extraídos de una página con la siguiente metaetiqueta:

<meta name="docsearch:version" content="2.0.0-alpha.62,latest" />

El atributo version de estos registros será:

version:["2.0.0-alpha.62" , "latest"]

Recomendaciones adicionales

• Tu sitio web debe tener un sitemap actualizado. Esto es clave para que nuestro crawler sepa qué debe actualizarse. No te preocupes, igualmente rastrearemos tu sitio web y descubriremos los hipervínculos incrustados para encontrar tu excelente contenido.

• Cada página debe tener su contexto completo disponible. El uso de elementos globales puede ayudar (consulta más arriba).

• Asegúrate que tu contenido documental esté disponible sin renderización JavaScript en el cliente. Si necesitas JavaScript activado, debes configurar js_render: true en tu configuración.

¿Preguntas? Conéctate con nosotros en Discord o contacta a nuestro equipo de soporte.