9.1 KiB

Raw Blame History

outline
deep

Buscar

Busqueda local

VitePress admite la búsqueda de texto completo utilizando un índice en el navegador gracias a minisearch. Para habilitar esta función, simplemente configure la opción themeConfig.search.provider como 'local' en el archivo .vitepress/config.ts:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

Resultado de ejemplo:

Alternativamente, puedes usar Algolia DocSearch o algunos complementos comunitarios como https://www.npmjs.com/package/vitepress-plugin-search o https://www.npmjs.com/package/vitepress-plugin-pagefind.

i18n

Puede utilizar una configuración como esta para utilizar la búsqueda multilingüe:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        locales: {
          zh: {
            translations: {
              button: {
                buttonText: '搜索文档',
                buttonAriaLabel: '搜索文档'
              },
              modal: {
                noResultsText: '无法找到相关结果',
                resetButtonTitle: '清除查询条件',
                footer: {
                  selectText: '选择',
                  navigateText: '切换'
                }
              }
            }
          }
        }
      }
    }
  }
})

Opciones MiniSearch

Puedes configurar MiniSearch de esta manera:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        miniSearch: {
          /**
           * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
           */
          options: {
            /* ... */
          },
          /**
           * @type {import('minisearch').SearchOptions}
           * @default
           * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } }
           */
          searchOptions: {
            /* ... */
          }
        }
      }
    }
  }
})

Obtenga más información en documentación de MiniSearch.

Presentador de contenido personalizado

Puedes personalizar la función utilizada para presentar el contenido de rebajas antes de indexarlo:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        /**
         * @param {string} src
         * @param {import('vitepress').MarkdownEnv} env
         * @param {import('markdown-it-async')} md
         */
        async _render(src, env, md) {
          // retorne un string HTML
        }
      }
    }
  }
})

Esta función se eliminará de los datos del sitio web en el lado del cliente, por lo que podrá utilizar las API de Node.js en ella.

Ejemplo: Excluir páginas de la busqueda

Puedes excluir páginas de la busqueda adicionando search: false al principio de la página. Alternativamente:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.search === false) return ''
          if (env.relativePath.startsWith('algum/caminho')) return ''
          return html
        }
      }
    }
  }
})

::: warning Nota En este caso, una función _render se proporciona, es necesario manipular el search: false desde el frente por su cuenta. Además, el objeto env no estará completamente poblado antes que md.renderAsync se llama, luego verifica las propiedades opcionales env, como frontmatter, debe hacerse después de eso. :::

Ejemplo: Transformar contenido - agregar anclajes

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local',
      options: {
        async _render(src, env, md) {
          const html = await md.renderAsync(src, env)
          if (env.frontmatter?.title)
            return await md.renderAsync(`# ${env.frontmatter.title}`) + html
          return html
        }
      }
    }
  }
})

Busqueda de Algolia

VitePress admite la búsqueda en su sitio de documentación utilizando Algolia DocSearch. Consulte su guía de introducción. en tu archivo .vitepress/config.ts, Deberá proporcionar al menos lo siguiente para que funcione:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...'
      }
    }
  }
})

i18n {#algolia-search-i18n}

Puedes utilizar una configuración como esta para utilizar la búsqueda multilingüe:

Haz clic para expandir

<<< @/snippets/algolia-i18n.ts

Consulta la documentación oficial de Algolia para conocer más detalles. Para empezar rápidamente, también puedes copiar las traducciones usadas por este sitio desde nuestro repositorio de GitHub.

Algolia Ask AI Support

Si deseas incluir Ask AI, pasa la opción askAi (o alguno de sus campos parciales) dentro de options:

options: {
  appId: '...',
  apiKey: '...',
  indexName: '...',
  // askAi: 'TU-ASSISTANT-ID'
  askAi: {
    assistantId: 'XXXYYY'
  }
}

::: warning Nota Si prefieres solo la búsqueda por palabra clave y no la Ask AI, simplemente omite askAi. :::

Panel lateral de Ask AI

DocSearch v4.5+ admite un panel lateral de Ask AI opcional. Cuando está habilitado, se puede abrir con Ctrl/Cmd+I por defecto. La Referencia de API del Panel Lateral contiene la lista completa de opciones.

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            // Refleja la API de @docsearch/sidepanel-js SidepanelProps
            panel: {
              variant: 'floating', // o 'inline'
              side: 'right',
              width: '360px',
              expandedWidth: '580px',
              suggestedQuestions: true
            }
          }
        }
      }
    }
  }
})

Si necesitas deshabilitar el atajo de teclado, usa la opción keyboardShortcuts del panel lateral:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        appId: '...',
        apiKey: '...',
        indexName: '...',
        askAi: {
          assistantId: 'XXXYYY',
          sidePanel: {
            keyboardShortcuts: {
              'Ctrl/Cmd+I': false
            }
          }
        }
      }
    }
  }
})

Modo (auto / sidePanel / hybrid / modal)

Puedes controlar opcionalmente cómo VitePress integra la búsqueda por palabra clave y Ask AI:

mode: 'auto' (por defecto): infiere hybrid cuando la búsqueda por palabra clave está configurada, de lo contrario sidePanel cuando el panel lateral de Ask AI está configurado.
mode: 'sidePanel': fuerza solo el panel lateral (oculta el botón de búsqueda por palabra clave).
mode: 'hybrid': habilita el modal de búsqueda por palabra clave + panel lateral de Ask AI (requiere configuración de búsqueda por palabra clave).
mode: 'modal': mantiene Ask AI dentro del modal de DocSearch (incluso si configuraste el panel lateral).

Solo Ask AI (sin búsqueda por palabra clave)

Si quieres usar solo el panel lateral de Ask AI, puedes omitir la configuración de búsqueda por palabra clave de nivel superior y proporcionar las credenciales bajo askAi:

import { defineConfig } from 'vitepress'

export default defineConfig({
  themeConfig: {
    search: {
      provider: 'algolia',
      options: {
        mode: 'sidePanel',
        askAi: {
          assistantId: 'XXXYYY',
          appId: '...',
          apiKey: '...',
          indexName: '...',
          sidePanel: true
        }
      }
    }
  }
})

Configuración Crawler

A continuación se muestra un ejemplo de la configuración que utiliza este sitio:

<<< @/snippets/algolia-crawler.js

9.1 KiB Raw Blame History