Búsqueda

Búsqueda

BX Sites incluye un proveedor de búsqueda por defecto y se puede apuntar a otros mediante 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 por defecto: un índice construido una vez en el momento de build, y lunr.js 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 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.
• 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

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

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

• la misma búsqueda alojada por un rastreador que admiten mkdocs-material, VitePress, Starlight y Docusaurus:

{
	"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 o por tu propia configuración de Algolia 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 - 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:

{
	"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. 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 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.