@mastra/docusaurus-theme

Mastra's Docusaurus theme, built on top of the default Docusaurus theme. This package contains:

• Custom components used inside MDX
• Custom theme and CSS styles
• Overrides for the default Docusaurus theme components

Installation

npm install @mastra/docusaurus-theme

Also install the required peer dependencies:

npm install @docusaurus/plugin-content-docs @docusaurus/theme-classic @docusaurus/theme-common @docusaurus/types @radix-ui/react-accordion @radix-ui/react-dropdown-menu clsx lucide-react react react-dom tailwindcss

Usage

import type { Config } from '@docusaurus/types'

const config: Config = {
	themes: ['@mastra/docusaurus-theme'],
}

export default config

Code Highlighting (Shiki)

The theme uses Shiki for syntax highlighting instead of Prism. All Shiki dependencies (shiki, @shikijs/rehype, @shikijs/transformers) are bundled with the theme — no extra installs needed.

Configure docusaurus.config.ts

import { shikiPlugin } from '@mastra/docusaurus-theme/shiki'

Then add shikiPlugin to every docs plugin instance via beforeDefaultRehypePlugins:

const config: Config = {
	presets: [
		['classic', {
			docs: {
				beforeDefaultRehypePlugins: [shikiPlugin],
			},
		}],
	],
	plugins: [
		['@docusaurus/plugin-content-docs', {
			beforeDefaultRehypePlugins: [shikiPlugin],
		}],
	],
}

The theme provides CSS variables for Shiki token colors (--shiki-foreground, --shiki-background, --shiki-token-*) that automatically adapt to light/dark mode. These are defined in the theme's vars.css.

Features

• Title bar: Use ```ts title="src/main.ts" to show a header with language icon, file path, and copy button
• Line highlighting: Use // [!code highlight] at the end of a line to highlight it

CSS features

LightningCSS is used to compile the CSS files. You can use all the features supported by LightningCSS, including:

• CSS nesting
• Custom media queries
• light-dark() function for color values

Read the tsdown.config.ts file for more details on the CSS configuration.