---
title: Búsqueda
order: 2
icon: phosphor-duotone:magnifying-glass
tags: [guías, búsqueda]
---

# Búsqueda

BX Sites incluye un proveedor de búsqueda por defecto y se puede apuntar
a otros mediante [`searchProvider`](../configuration.md#searchprovider)
de `bxsites.json` - `search: true`/`false` sigue siendo el interruptor
maestro de encendido/apagado, sin importar qué proveedor esté activo.

## Local (el predeterminado)

La búsqueda de BX Sites es completamente estática y del lado del
cliente - el mismo enfoque que usa [mkdocs](https://www.mkdocs.org/) por
defecto: un índice construido una vez en el momento de `build`, y
[lunr.js](https://lunrjs.com/) haciendo la búsqueda real en el navegador
del visitante. No hay servidor, base de datos ni servicio de búsqueda
externo involucrado.

## Cómo funciona

1. En el momento de `build`, `SearchIndexer` recorre cada página no
   oculta y escribe `site/search-index.json`: una entrada por página con
   su `title`, `url`, las `tags` del frontmatter, el texto de cada
   encabezado de la página, y una copia de texto plano truncada de su
   cuerpo (con las etiquetas HTML eliminadas).
2. El parcial `search.bxm` de cada tema renderiza un cuadro de búsqueda;
   `layout.bxm` solo lo incluye (junto con `lunr.js` y los scripts
   compartidos de `search.js`) cuando `search` de `bxsites.json` es
   `true` y `searchProvider.provider` es `"local"` (el predeterminado -
   consulta [Otros proveedores](#otros-proveedores-de-búsqueda) más
   abajo para lo que cambia con uno distinto).
3. En el navegador, el widget compartido `assets/search.js` obtiene
   `search-index.json` una vez, construye un índice `lunr` a partir de él
   (`title` con la mayor ponderación, luego las `tags` del frontmatter,
   luego `headings`, luego el texto plano del cuerpo), y vuelve a
   buscar en él en cada pulsación de tecla - sin ida y vuelta de red por
   consulta.

## Atajos de teclado

- **`/`** enfoca el cuadro de búsqueda desde cualquier lugar de la página
  (a menos que ya estés escribiendo en otro campo) - la misma convención
  que usa [mkdocs-material](https://squidfunk.github.io/mkdocs-material/).
- **Cmd/Ctrl+K** también lo enfoca, desde cualquier lugar - incluso
  mientras escribes en otro campo - la convención que comparten Algolia
  DocSearch, Pagefind, VitePress y Docusaurus. El cuadro de búsqueda
  muestra una pequeña pista `Ctrl K`/`⌘K` (detectada según la
  plataforma) para que sea descubrible.
- **`Escape`** cierra el desplegable de resultados y quita el foco del
  cuadro de búsqueda.

Cmd/Ctrl+K funciona de la misma forma para cada proveedor - el propio
widget de `local` lo vincula directamente, `algolia` lo obtiene gratis
del propio DocSearch (`keyboardShortcuts` es `true` por defecto), y
`pagefind` lo obtiene conectado por `layout.bxm`, ya que `PagefindUI` no
lo vincula por sí mismo.

## Desactivarla

```json title="bxsites.json"
{ "search": false }
```

Omite la construcción de `search-index.json` por completo, y omite el
cuadro de búsqueda, el script incluido/autoalojado de `lunr.js`, y el
widget compartido `search.js` en cada página renderizada - un proyecto
con la búsqueda desactivada no envía nada relacionado con búsqueda en
absoluto. Este es el interruptor maestro - se aplica sin importar qué
`searchProvider` esté configurado.

## Reconstruir solo el índice

```bash frame="terminal" title="Terminal"
bxSites search-index
```

Útil si solo necesitas actualizar `search-index.json` - `build` ya hace
esto como uno de sus propios pasos, así que no necesitas ejecutar esto
por separado después de una construcción normal. Solo se ejecuta para
proveedores que usan el índice local (`"local"`, y cualquier proveedor
que bx-sites no conozca de otro modo) - es un no-op (`skipped: true`)
cuando `searchProvider.provider` es `"algolia"` o `"pagefind"`, ya que
ninguno de los dos lo usa nunca.

## Algolia

Establece `searchProvider.provider` en `"algolia"` para sustituir el
cuadro de búsqueda por [Algolia DocSearch](https://docsearch.algolia.com/)
- la misma búsqueda alojada por un rastreador que admiten
mkdocs-material, VitePress, Starlight y Docusaurus:

```json title="bxsites.json" linenums="1"
{
	"search": true,
	"searchProvider": {
		"provider": "algolia",
		"algolia": {
			"appId": "ABC123",
			"apiKey": "a1b2c3d4e5f6...",
			"indexName": "my-docs",
			"insights": false
		}
	}
}
```

`appId`, `apiKey` e `indexName` son obligatorios - `apiKey` es la clave
API pública **solo de búsqueda** que te da DocSearch (nunca una clave de
administrador; se envía directamente en cada página renderizada).
`insights` (`false` por defecto) activa la propia analítica de
clics/conversión de DocSearch.

Con `algolia` activo:

- No se construye ningún `search-index.json`, y el widget compartido
  `lunr.js`/`search.js` no se incluye - Algolia sirve los resultados
  desde su propio índice alojado, poblado por el
  [rastreador de DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch/)
  o por tu propia configuración de
  [Algolia Crawler](https://www.algolia.com/products/search-and-discovery/crawler/),
  no por nada que BX Sites escriba en el momento de la construcción.
  Igualmente necesitas registrar el sitio con DocSearch (o ejecutar tu
  propio rastreador) por separado - BX Sites solo conecta el widget del
  cliente.
- Cada tema incorporado renderiza en su lugar un contenedor vacío
  `#bxsites-search-algolia`, y `layout.bxm` carga `@docsearch/css`/
  `@docsearch/js` desde jsDelivr y llama a `docsearch({...})` contra él -
  DocSearch renderiza su propio botón de búsqueda y modal dentro de ese
  contenedor.

## Pagefind

Establece `searchProvider.provider` en `"pagefind"` para sustituir el
cuadro de búsqueda por [Pagefind](https://pagefind.app/) - otro motor de
búsqueda totalmente estático/sin servidor, pero indexado a partir del
propio HTML *construido* de `site/` en lugar de rastreado como Algolia:

```json title="bxsites.json" linenums="1"
{
	"search": true,
	"searchProvider": {
		"provider": "pagefind",
		"pagefind": { "bin": "pagefind", "options": [] }
	}
}
```

Ambas claves de `pagefind` son opcionales - `bin` (por defecto
`"pagefind"`) es el nombre/ruta del ejecutable, resuelto contra `PATH`
cuando es un nombre simple; `options` es un array de flags de CLI en
bruto adicionales pasados directamente (por ejemplo
`["--exclude-selectors", ".no-index"]`).

Con `pagefind` activo:

- **El propio CLI de `pagefind` ya debe estar instalado y en `PATH`** -
  BX Sites lo invoca mediante shell (no hay un binding nativo de
  BoxLang, la misma razón por la que `lastUpdated`/`gh-deploy` invocan
  `git` mediante shell), no lo instala por ti. Consulta la
  [propia documentación de instalación de Pagefind](https://pagefind.app/docs/installation/).
  A diferencia de `lastUpdated`, un binario ausente/fallido hace fallar
  `build` de forma explícita (`BxSites.PagefindFailed`) en lugar de
  degradarse silenciosamente - publicar un sitio cuyo proveedor de
  búsqueda configurado no funciona es peor que una construcción fallida.
- Justo después de que cada árbol de documentación (principal + versiones
  + idiomas) se escribe y se generan `sitemap.xml`/`llms.txt`, BX Sites
  ejecuta `pagefind --site <siteDir> [...options]` contra *todo* el
  `site/` construido - así que un sitio multiversión/multiidioma obtiene
  todo indexado en un solo paso, a diferencia del propio
  `search-index.json` por árbol de bx-sites. Pagefind escribe su propio
  paquete directamente en `site/pagefind/` - autoalojado, sin CDN
  involucrado.
- No se construye ningún `search-index.json`, y el widget compartido
  `lunr.js`/`search.js` no se incluye (igual que con `algolia`) - y
  `bxSites search-index` es un no-op por la misma razón (consulta
  arriba).
- Cada tema incorporado renderiza un contenedor vacío
  `#bxsites-search-pagefind`, y `layout.bxm` carga
  `site/pagefind/pagefind-ui.{css,js}` y llama a
  `new PagefindUI({...})` contra él - Pagefind renderiza su propio
  cuadro de búsqueda y resultados en línea dentro de ese contenedor.

## Otros proveedores de búsqueda

`searchProvider.provider` no está limitado a
`"local"`/`"algolia"`/`"pagefind"` - cualquier otro valor es aceptado
por `bxsites.json` tal cual (la propia validación de configuración de BX
Sites solo comprueba los tres proveedores de arriba). No hay ningún hook
de plugin para esto - los temas incorporados simplemente no renderizan
nada para un nombre de proveedor no reconocido, y conectar un cuarto
servicio de búsqueda (Meilisearch, Typesense, etc.) es una
[sobrescritura de tema](themes.md#sobrescribir-un-tema) a nivel de
proyecto: copia un tema incorporado en el propio `theme/` de tu proyecto
y añade el marcado/scripts de tu proveedor a su `layout.bxm`/
`search.bxm`, leyendo `siteConfig.searchProvider` para decidir cuándo
renderizarlos - ramas `searchProviderName eq "..."` para el punto de
montaje en `search.bxm`, ramas equivalentes en `layout.bxm` para su
CSS/JS, y (si no está alojado por un rastreador como Algolia) cualquier
paso de indexación que ese producto necesite contra `site/` después de
`build` - la misma forma que ya usan el propio `layout.bxm`/
`BuildPipeline.bx` de este módulo para `algolia`/`pagefind`.