BxSites Search Providers Reference

search: true/false (in bxsites.yaml - see bx-sites-configuration) is the master on/off switch regardless of which searchProvider.provider is active.

local (default)

Fully static/client-side - the mkdocs default approach. At build time, SearchIndexer writes site/search-index.json: one entry per page with title, url, frontmatter tags, every heading's text, and a truncated plain-text body copy. In the browser, assets/search.js fetches it once and builds a MiniSearch index (prefix + typo-tolerant fuzzy matching, both on by default; title weighted highest, then tags, then headings, then body). No server/database/external service.

Shortcuts: / focuses the sidebar box; Cmd/Ctrl+K opens a command-palette overlay (reuses the same MiniSearch index, local only); Escape closes either.

bxSites search-index

rebuilds just the index (build already runs this; useful standalone - see bx-sites-build). bxSites search:query --query="..." (see bx-sites-content-quality) sanity-checks what a real search would surface.

algolia

```yaml title="bxsites.yaml" search: true searchProvider: provider: algolia algolia: appId: ABC123 apiKey: a1b2c3d4e5f6... # search-only public key, NEVER an admin key indexName: my-docs insights: false

`appId`/`apiKey`/`indexName` required. With Algolia active: no
`search-index.json` is built, no MiniSearch/`search.js` shipped - results
come from Algolia's own hosted index, populated by DocSearch's crawler or
your own Algolia Crawler config (register separately - bx-sites only wires
up the client widget). Each theme renders an empty
`#bxsites-search-algolia` container; `layout.bxm` loads `@docsearch/css`/
`@docsearch/js` from jsDelivr and calls `docsearch({...})`. Gets Cmd+K for
free from DocSearch itself.

## `pagefind`

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

Both keys optional (bin default "pagefind", resolved against PATH; options extra raw CLI flags, e.g. ["--exclude-selectors", ".no-index"]). The pagefind CLI must already be installed and on PATH - bx-sites shells out to it, doesn't install it. A missing/failing binary fails the build loudly (BxSites.PagefindFailed) rather than degrading silently. Right after every doc tree + sitemap.xml/llms.txt are written, bx-sites runs pagefind --site <siteDir> [...options] against the entire built site/ (indexes a multi-version/multi-locale site in one pass, unlike local's per-tree index - see bx-sites-blog-versioning-i18n for versions/locales). Writes into site/pagefind/ - self-hosted, no CDN. No search-index.json; bxSites search-index is a no-op for this provider.

Choosing a provider

Building a fourth/custom provider

searchProvider.provider accepts any string - bxsites.yaml only validates the three built-in providers and freely allows an arbitrary sub-block alongside it (searchProvider.meilisearch: {...}). There's no plugin hook for the search UI itself; the built-in themes render nothing for an unrecognized provider name, so wiring one up is a project-level theme override (see bx-sites-themes):

1. Configure it - any shape (unvalidated):

``yaml search: true searchProvider: provider: meilisearch meilisearch: { host: https://my-project.meilisearch.io, apiKey: "...", indexName: my-docs } ``

1. Eject a theme - bxSites theme:new --theme=bootstrap copies the

built-in theme into project theme/ (project-theme-wins resolution).

1. Add the mount point in theme/search.bxm - it already branches on

variables.searchProviderName for local/algolia/pagefind; add a branch: <bx:if variables.searchProviderName eq 'meilisearch'><div id="bxsites-search-meilisearch"></div></bx:if>.

1. Load the client and wire it up in theme/layout.bxm - the existing

Algolia block is a <bx:if variables.searchEnabled and variables.searchProviderName eq 'algolia'> guard; add the equivalent for the new provider's own widget, reading its config back out of variables.siteConfig.searchProvider.meilisearch.*.

1. Index the built site, if not crawler-hosted - Algolia's own crawler

populates out of band; a self-hosted engine like Meilisearch/Pagefind needs something to push documents after build writes site/. Use a plugin's onBuildComplete( siteDir, config ) hook (see bx-sites-plugins) - site/search-index.json is still built even for an unrecognized provider (SearchProviderRegistry.usesLocalIndex() defaults true), so it's ready to use as the push payload.