Búsqueda

Búsqueda

BxSites incluye un proveedor de búsqueda por defecto y se puede apuntar a otros mediante searchProvider de bxsites.yaml - search: true/false sigue siendo el interruptor maestro de encendido/apagado, sin importar qué proveedor esté activo.

Local (el predeterminado)

La búsqueda de BxSites 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.yaml 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 de la barra lateral 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. El cuadro de búsqueda muestra una pequeña pista Ctrl K/⌘K (detectada según la plataforma) para que el atajo de abajo sea descubrible.
• Cmd/Ctrl+K en su lugar abre una superposición aparte, al estilo paleta de comandos - una ventana modal centrada sobre un fondo oscurecido, construida enteramente en JS (sin necesidad de cambios en las plantillas de tema) y compartida por todos los temas incorporados. Las flechas arriba/abajo mueven un resaltado entre los resultados, Enter navega hasta el resultado resaltado, y Escape (o hacer clic en el fondo oscurecido) la cierra - la misma convención de "Búsqueda rápida"/⌘K que comparten Algolia DocSearch, Pagefind, VitePress, Docusaurus y GitBook.
• Escape también cierra el propio desplegable de resultados del cuadro de la barra lateral y le quita el foco, de forma independiente a la paleta de arriba.

La paleta reutiliza exactamente el mismo índice lunr ya construido que construye el propio widget de la barra lateral, en lugar de obtener search-index.json una segunda vez - solo está disponible para local (el proveedor por defecto); algolia obtiene su propio Cmd+K gratis del propio DocSearch (keyboardShortcuts es true por defecto), y pagefind obtiene Cmd+K conectado por layout.bxm para enfocar su propio PagefindUI, ya que esa biblioteca no lo vincula por sí misma - ninguno de los dos abre la propia paleta de este módulo.

Desactivarla

search: false

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

{
	"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 BxSites escriba en el momento de la construcción. Igualmente necesitas registrar el sitio con DocSearch (o ejecutar tu propio rastreador) por separado - BxSites 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: [] }

{
	"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 - BxSites 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, BxSites 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.yaml 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.