Saltar al contenido principal
Versión: Legado (v3.x)

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 te brinda las mejores prácticas para optimizar nuestro rastreo. Adoptar las siguientes especificaciones es necesario para permitir que nuestro crawler construya la mejor experiencia desde tu sitio web. Deberás actualizar tu sitio y seguir estas reglas.

información

Si tu sitio web está generado con alguna de nuestras herramientas compatibles, no necesitas realizar cambios ya que cumple con nuestros requisitos.

Ejemplo de configuración genérica​

Puedes encontrar la plantilla de configuración predeterminada de DocSearch a continuación y ajustarla con ejemplos de nuestra sección de complex extractors.

Si estás usando alguna de nuestras integraciones, consulta la página de plantillas.

docsearch-default.js
new Crawler({
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_API_KEY',
  startUrls: ['https://YOUR_START_URL.io/'],
  sitemaps: ['https://YOUR_START_URL.io/sitemap.xml'],
  actions: [
    {
      indexName: 'YOUR_INDEX_NAME',
      pathsToMatch: ['https://YOUR_START_URL.io/**'],
      recordExtractor: ({ helpers }) => {
        return helpers.docsearch({
          recordProps: {
            lvl0: {
              selectors: '',
              defaultValue: 'Documentation',
            },
            lvl1: ['header h1', 'article h1', 'main h1', 'h1', 'head > title'],
            lvl2: ['article h2', 'main h2', 'h2'],
            lvl3: ['article h3', 'main h3', 'h3'],
            lvl4: ['article h4', 'main h4', 'h4'],
            lvl5: ['article h5', 'main h5', 'h5'],
            lvl6: ['article h6', 'main h6', 'h6'],
            content: ['article p, article li', 'main p, main li', 'p, li'],
          },
          aggregateContent: true,
          recordVersion: 'v3',
        });
      },
    },
  ],
  initialIndexSettings: {
    YOUR_INDEX_NAME: {
      attributesForFaceting: ['type', 'lang'],
      attributesToRetrieve: [
        'hierarchy',
        'content',
        'anchor',
        'url',
        'url_without_anchor',
        'type',
      ],
      attributesToHighlight: ['hierarchy', 'content'],
      attributesToSnippet: ['content:10'],
      camelCaseAttributes: ['hierarchy', 'content'],
      searchableAttributes: [
        'unordered(hierarchy.lvl0)',
        'unordered(hierarchy.lvl1)',
        'unordered(hierarchy.lvl2)',
        'unordered(hierarchy.lvl3)',
        'unordered(hierarchy.lvl4)',
        'unordered(hierarchy.lvl5)',
        'unordered(hierarchy.lvl6)',
        'content',
      ],
      distinct: true,
      attributeForDistinct: 'url',
      customRanking: [
        'desc(weight.pageRank)',
        'desc(weight.level)',
        'asc(weight.position)',
      ],
      ranking: [
        'words',
        'filters',
        'typo',
        'attribute',
        'proximity',
        'exact',
        'custom',
      ],
      highlightPreTag: '<span class="algolia-docsearch-suggestion--highlight">',
      highlightPostTag: '</span>',
      minWordSizefor1Typo: 3,
      minWordSizefor2Typos: 7,
      allowTyposOnNumericTokens: false,
      minProximity: 1,
      ignorePlurals: true,
      advancedSyntax: true,
      attributeCriteriaComputedByMinProximity: true,
      removeWordsIfNoResults: 'allOptional',
      separatorsToIndex: '_',
    },
  },
});

Visión general de un diseño claro​

Un sitio web que implemente estas buenas prácticas lucirá simple y completamente claro. Puede tener esta apariencia:

Recommended layout for your page

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

Usar las clases correctas como recordProps​

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.

  • Todo elemento DOM que coincida con los selectores lvlX debe tener un atributo id o name único. Esto ayudará a que la redirección desplace directamente al lugar exacto de los elementos coincidentes. Estos atributos definen el ancla correcta a usar.

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

  • Mantén consistencia y recuerda que necesitamos uniformidad a lo largo del flujo HTML.

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.

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"]

Puedes entonces transformar estos atributos en facetFilters para filtrarlos desde la interfaz.

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 de que el contenido de tu documentación también esté disponible sin renderización de JavaScript en el cliente. Si realmente necesitas tener JavaScript activado, debes configurar renderJavaScript: true en tu configuración.

¿Tienes preguntas? Conéctate con nosotros en Discord o soporte.