@mastra/docusaurus-plugin-kapa

Kapa.ai assistant plugin for Docusaurus. Adds an AI-powered chatbot sidebar to your documentation site, using Kapa's SDK to answer questions based on your docs.

Installation

npm install @mastra/docusaurus-plugin-kapa

Also install the required peer dependencies:

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

Usage

1. Register the plugin

Add it as a theme (not a plugin) in docusaurus.config.ts:

import type { Config } from '@docusaurus/types'
import type { KapaPluginOptions } from '@mastra/docusaurus-plugin-kapa'

const config: Config = {
	themes: [
		[
			'@mastra/docusaurus-plugin-kapa',
			{
				integrationId: process.env.KAPA_INTEGRATION_ID,
				groupId: process.env.KAPA_GROUP_ID, // Optional
			} satisfies KapaPluginOptions,
		],
	],
}

export default config

2. Wire up in src/theme/Root.tsx

The plugin provides theme components but does not inject its own Root.tsx. You must wrap your app with DocsChatProvider in your site's Root.tsx:

import type { ReactNode } from 'react'
import { DocsChatProvider } from '@mastra/docusaurus-plugin-kapa/client'

function KapaWrapper({ children }: { children: ReactNode }) {
	return <DocsChatProvider>{children}</DocsChatProvider>
}

export default function Root({ children }: { children: ReactNode }) {
	return <KapaWrapper>{children}</KapaWrapper>
}

3. Edit your styles.css

Add the required @import statements to your styles.css:

@import '@mastra/docusaurus-plugin-kapa';

4. Add a navbar toggle (optional)

Register DocsChatToggle as a custom navbar item. In your NavbarItem/ComponentTypes.tsx:

import { DocsChatToggle } from '@mastra/docusaurus-plugin-kapa/client'
import OriginalComponentTypes from '@theme-original/NavbarItem/ComponentTypes'

export default {
	...OriginalComponentTypes,
	'custom-kapaChat': DocsChatToggle,
}

Then add it to your navbar config when the Kapa theme is enabled:

const ENABLE_KAPA = Boolean(process.env.KAPA_INTEGRATION_ID)

export default {
	themeConfig: {
		navbar: {
			items: [
				...(ENABLE_KAPA
					? [{ type: 'custom-kapaChat', position: 'right' as const }]
					: []),
			],
		},
	},
}

Options

| Option | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------------------------------ | | integrationId | string | Yes | Your Kapa.ai integration ID | | groupId | string | No | Kapa source group ID for filtering which docs are searchable |