@mastra/docusaurus-plugin-algolia

Custom Algolia search plugin for Docusaurus. Replaces the default search with a modal-based search UI featuring keyboard navigation, virtual scrolling, recent searches, and suggested links.

Installation

npm install @mastra/docusaurus-plugin-algolia

Also install the required peer dependencies:

npm install @docusaurus/types clsx lucide-react react react-dom

Usage

Register the plugin in docusaurus.config.ts:

import type { Config } from '@docusaurus/types'
import type { AlgoliaPluginOptions } from '@mastra/docusaurus-plugin-algolia'

const config: Config = {
	plugins: [
		[
			'@mastra/docusaurus-plugin-algolia',
			{
				algoliaAppId: process.env.ALGOLIA_APP_ID,
				algoliaSearchApiKey: process.env.ALGOLIA_SEARCH_API_KEY,
				indexName: 'docs_v1_crawler',
				hitsPerPage: 20,
				suggestedLinks: [
					{
						label: 'Quickstart',
						description: 'Get up and running',
						link: '/docs/get-started/overview',
					},
				],
			} satisfies AlgoliaPluginOptions,
		],
	],
}

export default config

Options

| Option | Type | Required | Default | Description | | --------------------- | ----------------- | -------- | ---------------- | ------------------------------------------ | | algoliaAppId | string | Yes | — | Algolia application ID | | algoliaSearchApiKey | string | Yes | — | Algolia search-only API key | | indexName | string | No | 'docs_crawler' | Algolia index name | | hitsPerPage | number | No | 20 | Results per page | | suggestedLinks | SuggestedLink[] | No | [] | Links shown when the search input is empty |

Each SuggestedLink has label, description, and link fields.

Features

• Search modal — Opens with Cmd+K / Ctrl+K, built on Radix UI Dialog
• Virtual scrolling — Efficiently renders large result sets via @tanstack/react-virtual
• Section grouping — Results grouped by section (Docs, Guides, Reference, Examples) with sticky headers
• Keyboard navigation — Arrow keys, Enter, Escape, Tab
• Recent searches — Last 5 searches persisted in localStorage
• Suggested links — Configurable links shown in the empty state
• Result highlighting — Matched terms highlighted in results
• Load more — Paginated results with on-demand loading
• Dark mode — Fully themed with CSS variables from @mastra/docusaurus-theme

How It Works

The plugin provides a SearchBar theme component via getThemePath(). Configuration is passed to the frontend through Docusaurus's setGlobalData() / usePluginData() pattern, so API keys never appear in client bundles beyond what Algolia's search-only key allows.