{props.title}
{props.children}{props.children}
;
}
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultMdxComponents,
// updated accordions:
Accordion: isPrinting ? PrintingAccordion : Accordion,
Accordions: isPrinting ? PrintingAccordions : Accordions,
...components,
} satisfies MDXComponents;
}
```
# Fumadocs (Framework Mode): Guides
URL: /docs/guides
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/guides/index.mdx
Useful guides for extending Fumadocs.
{slots.header}
{slots.description}
{slots.channel}
{slots.parameters}
{slots.messages}
);
},
},
});
```
### Schema UI [#schema-ui]
Customize how JSON schemas are rendered, or disable schema examples.
```tsx title="components/api-page.tsx"
'use client';
import { createAsyncAPIPage } from '@fumadocs/asyncapi/ui';
export const AsyncAPIPage = createAsyncAPIPage({
schemaUI: {
showExample: true,
render(options, ctx) {
// fully custom schema renderer
return ctx.SchemaUI(options);
},
},
});
```
### Internationalization [#internationalization]
Assuming you have configured [Internationalization](/docs/internationalization) at UI level:
```tsx title="layout.shared.tsx"
import { defineI18n } from 'fumadocs-core/i18n';
import { uiTranslations } from 'fumadocs-ui/i18n';
import { asyncapiTranslations } from '@fumadocs/asyncapi/i18n';
const i18n = defineI18n({
languages: ['en', 'cn'],
defaultLanguage: 'en',
});
export const translations = i18n
.translations()
.extend(uiTranslations())
// [!code ++]
.extend(asyncapiTranslations())
.add({
cn: {
displayName: 'Chinese'
// [!code ++]
'Messages(operation page)': '消息',
},
})
```
See [Translations](/docs/ui/translations) for more details.
### Syntax Highlighting [#syntax-highlighting]
AsyncAPI pages use Shiki for code blocks. You can customize the highlighter and themes.
```tsx title="components/api-page.tsx"
'use client';
import { createAsyncAPIPage } from '@fumadocs/asyncapi/ui';
import { defaultShikiFactory } from 'fumadocs-core/highlight/shiki/full';
export const AsyncAPIPage = createAsyncAPIPage({
shiki: defaultShikiFactory,
shikiOptions: {
themes: {
light: 'github-light',
dark: 'github-dark',
},
},
});
```
### Custom Components [#custom-components]
Override the default heading and code block components.
```tsx title="components/api-page.tsx"
'use client';
import { createAsyncAPIPage } from '@fumadocs/asyncapi/ui';
export const AsyncAPIPage = createAsyncAPIPage({
components: {
Heading({ id, depth, ...props }) {
const Tag = `h${depth}` as const;
return {code};
},
},
});
```
## Customise UI [#customise-ui]
For customisations beyond the available options, you can install the UI into your codebase with [Fumadocs CLI](/docs/cli).
### Full UI [#full-ui]
The entire UI of API pages, built on [the headless layer](/docs/integrations/asyncapi/headless).
```npm
npx @fumadocs/cli add asyncapi/page
```
It installs `
{code}
);
},
},
});
```
| Component | Renders |
| ----------- | ------------------------------------------------------------ |
| `Operation` | each operation of the page, see [Operation](#operation) |
| `SchemaUI` | the JSON schemas of parameters, headers and message payloads |
| `Layout` | optional, wraps the rendered operations |
### Hooks [#hooks]
Components under the page read its state.
| Hook | Returns |
| -------------------- | -------------------------------------------------- |
| `useAsyncAPI()` | the dereferenced document (`doc`) and page options |
| `useComponents()` | the components passed to the page |
| `useServer()` | the servers, the selected one and its variables |
| `useRenderContext()` | the render options of the page, like `content` |
To render operations yourself, mount `{title}
{channel.address}
-
{parameters.map((param) => (
- {param.name} ))}
{message.name}
{message.examples.map((example) => ({JSON.stringify(example.payload, null, 2)}
))}
{schemes.map((scheme) => scheme.type).join(', ')}
); } ``` | Hook | Returns | | ------------------------ | ------------------------------------------------------------------------ | | `useOperation()` | the operation with its details resolved | | `useOperationSecurity()` | security schemes of the operation, falling back to the selected server's | ### OperationInfo | Prop | Type | Description | | -------------- | -------- | ----------------------------- | | `id` | `string` | | | `action` | `union` | | | `operation` | `object` | resolved, with traits applied | | `channel` | `object` | | | `title` | `string` | | | `description?` | `string` | | | `parameters` | `array` | | | `messages` | `array` | | | `reply?` | `object` | | Examples of a message come from the document, or are generated from its schemas. ### OperationMessage | Prop | Type | Description | | ---------- | -------- | ----------------------------------- | | `id` | `string` | id for anchors and accordion values | | `name` | `string` | display name | | `message` | `object` | resolved, with traits applied | | `headers?` | `union` | | | `payload?` | `union` | | | `examples` | `array` | example messages | # Fumadocs (Framework Mode): AsyncAPI URL: /docs/integrations/asyncapi Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/integrations/asyncapi/index.mdx Generating docs for AsyncAPI schema. ## Setup [#setup] Install the required packages. ```npm npm i @fumadocs/asyncapi shiki ``` ### Generate Styles [#generate-styles] Add the following line: ```css title="Tailwind CSS" @import 'tailwindcss'; @import 'fumadocs-ui/css/neutral.css'; @import 'fumadocs-ui/css/preset.css'; /* [!code ++] */ @import '@fumadocs/asyncapi/css/preset.css'; ``` ### Configure Plugin [#configure-plugin] Create the AsyncAPI server instance & `{page.data.title}
{page.data.title}
{page.data.description}
### Installation [#installation]
```npm
npm i fumadocs-mdx fumadocs-core @types/mdx
```
Add the plugin to Next.js config:
```js title="next.config.mjs"
import { createMDX } from 'fumadocs-mdx/next';
/** @type {import('next').NextConfig} */
const config = {
reactStrictMode: true,
};
// [!code ++:4]
const withMDX = createMDX();
// [!code highlight]
export default withMDX(config);
```
Fumadocs MDX is ESM-only, it's recommended to use `next.config.mjs` for accurate ESM resolution.
For TypeScript config file, it requires Native Node.js TypeScript Resolver, you can see [Next.js docs](https://nextjs.org/docs/app/api-reference/config/typescript#using-nodejs-native-typescript-resolver-for-nextconfigts) for details.
### Integrate with Fumadocs [#integrate-with-fumadocs]
Create a `lib/source.ts` file:
```ts title="lib/source.ts"
import { defineDocs } from 'fumadocs-mdx/macro';
import { loader } from 'fumadocs-core/source';
const docs = defineDocs({
dir: 'content/docs',
});
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
### Done [#done]
You can now write content in `content/docs` folder.
Hello World
// [\!code highlight]
// highlight a word
// [\!code word:Fumadocs]
Fumadocs
// diff styles
console.log('hewwo'); // [\!code --]
console.log('hello'); // [\!code ++]
// focus
return new ResizeObserver(() => {}) // [\!code focus]
```
````
```tsx tab="Output"
// highlight a line
Hello World
// [!code highlight]
// highlight a word
// [!code word:Fumadocs]
Fumadocs
// diff styles:
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]
// focus
return new ResizeObserver(() => {}) // [!code focus]
```
#### Tab Groups [#tab-groups]
````mdx
```ts tab="Tab 1"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```
````
```ts tab="Tab 1"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```
To add a persist ID, define `tab-group` at the first codeblock:
````mdx
```ts tab="Tab 1" tab-group="my-custom-group"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```
````
```ts tab="Tab 1" tab-group="my-custom-group"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```
Another group:
```ts tab="Tab 1" tab-group="my-custom-group"
console.log('A');
```
```ts tab="Tab 2"
console.log('B');
```
#### MDX in Tab Groups [#mdx-in-tab-groups]
While disabled by default, you use MDX in tab values by configuring the remark plugin:
```ts tab="Fumadocs MDX" title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkCodeTabOptions: {
parseMdx: true, // [!code ++]
},
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkCodeTab } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [
[
remarkCodeTab,
{
parseMdx: true, // [!code ++]
},
],
],
});
```
````mdx
```ts tab=" {
if (container) bindFunctions?.(container);
}}
dangerouslySetInnerHTML={{ __html: svg }}
/>
);
}
```
### Beautiful Mermaid [#beautiful-mermaid]
[`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid) is a 3rd party Mermaid renderer.
```npm
npm install beautiful-mermaid
```
```tsx title="components/mdx/mermaid.tsx"
import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';
import { renderMermaidSVG } from 'beautiful-mermaid';
export async function Mermaid({ chart }: { chart: string }) {
try {
const svg = renderMermaidSVG(chart, {
bg: 'var(--color-fd-background)',
fg: 'var(--color-fd-foreground)',
interactive: true,
transparent: true,
});
return ;
} catch {
return (
);
}
}
```
## Usage [#usage]
Add the component as a MDX component:
```tsx title="components/mdx.tsx"
import defaultMdxComponents from 'fumadocs-ui/mdx';
import { Mermaid } from '@/components/mdx/mermaid'; // [!code ++]
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultMdxComponents,
Mermaid, // [!code ++]
...components,
} satisfies MDXComponents;
}
```
Then, use it in MDX files.
```mdx
### As CodeBlock [#as-codeblock]
You can convert `mermaid` codeblocks into the MDX usage with the `remarkMdxMermaid` remark plugin.
```tsx tab="Fumadocs MDX" title="source.config.ts"
import { remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkMdxMermaid],
},
});
```
````md
```mermaid
graph TD;
A-->B;
A-->C;
```
````
# Fumadocs (Framework Mode): Twoslash
URL: /docs/markdown/twoslash
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/markdown/twoslash.mdx
Use Typescript Twoslash in your docs
## Usage [#usage]
Thanks to the Twoslash integration of [Shiki](https://github.com/shikijs/shiki), the default code syntax highlighter, it is as simple as adding a transformer.
Type information is resolved by the native TypeScript 7 compiler, from the working directory of your project.
```package-install
fumadocs-twoslash
```
> While being analyzed, code blocks are briefly written to the `.twoslash` directory, add it to your `.gitignore`.
For Next.js, you need to externalize the following deps:
```js title="next.config.mjs (Next.js)"
const config = {
reactStrictMode: true,
// [!code ++]
serverExternalPackages: ['typescript'],
};
```
Add to your Shiki transformers.
```ts title="source.config.ts (Fumadocs MDX)"
import { defineConfig } from 'fumadocs-mdx/config';
import { transformerTwoslash } from 'fumadocs-twoslash';
import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins';
export default defineConfig({
mdxOptions: {
rehypeCodeOptions: {
themes: {
light: 'github-light',
dark: 'github-dark',
},
transformers: [...(rehypeCodeDefaultOptions.transformers ?? []), transformerTwoslash()],
// important: Shiki doesn't support lazy loading languages for codeblocks in Twoslash popups
// make sure to define them first (e.g. the common ones)
langs: ['js', 'jsx', 'ts', 'tsx'],
},
},
});
```
Add styles, Tailwind CSS v4 is required.
```css title="Tailwind CSS"
@import 'fumadocs-twoslash/twoslash.css';
```
Add MDX components.
```tsx title="components/mdx.tsx"
import * as Twoslash from 'fumadocs-twoslash/ui'; // [!code ++]
import defaultComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultComponents,
// [!code ++]
...Twoslash,
...components,
} satisfies MDXComponents;
}
```
Now you can add `twoslash` meta string to codeblocks.
````md
```ts twoslash
console.log('Hello World');
```
````
### Cache [#cache]
Optionally, you can enable filesystem cache with `typesCache` option:
```ts twoslash title="source.config.ts"
import { transformerTwoslash } from 'fumadocs-twoslash';
import { createFileSystemTypesCache } from 'fumadocs-twoslash/cache-fs';
transformerTwoslash({
typesCache: createFileSystemTypesCache(),
});
```
### Example [#example]
Learn more about [Twoslash notations](https://twoslash.netlify.app/refs/notations).
````ts twoslash tab="Output" lineNumbers
type Player = {
/**
* The player name
* ```php
* $a = "60"
* ```
*
* @default 'user'
*/
name: string;
};
/**
* A custom function.
*
* @example
*
* ```ts
* const str = fn("hello world")
* console.log(str)
* ```
*/
function fn(s: T): T {
return s;
}
// ---cut---
// @noErrors
console.g;
// ^|
const player: Player = { name: 'Hello World' };
// ^?
fn('test');
````
`````md tab="Input" lineNumbers
````ts twoslash lineNumbers
type Player = {
/**
* The player name
* ```php
* $a = "60"
* ```
*
* @default 'user'
*/
name: string;
};
/**
* A custom function.
*
* @example
*
* ```ts
* const str = fn("hello world")
* console.log(str)
* ```
*/
function fn(s: T): T {
return s;
}
// ---cut---
// @noErrors
console.g;
// ^|
const player: Player = { name: 'Hello World' };
// ^?
fn('test');
````
`````
```ts twoslash
const a = '123';
console.log(a);
// ^^^
```
```ts twoslash
// @errors: 2588
const a = '123';
a = 132;
```
# Fumadocs (Framework Mode): Navigation
URL: /docs/navigation
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/navigation.mdx
Organize sidebar pages, link to other resources, and publish multiple versions of your docs.
## Overview [#overview]
**Fumadocs UI** provides different layouts to display content, you can specify navigation configurations via layouts.
## Versioning [#versioning]
Keep multiple versions available when readers need documentation for older releases. Choose whether versions share a site or have separate deployments:
| Approach | When |
| ----------------------------------- | ----------------------------------------------------------------------- |
| [Root Type](#root-type) | Versioning applies to part of your docs, versions live in the same site |
| [Full Versioning](#full-versioning) | Versioning the entire website, one deployment per version |
### Root Type [#root-type]
Create a folder for each version, and mark them as root folders of the same type in `meta.json`:
```json tab="v1/meta.json"
{
"title": "1.0.0",
"root": "version"
}
```
```json tab="v2/meta.json"
{
"title": "2.0.0",
"root": "version"
}
```
The sidebar only shows the content of the opened version, and docs layouts render a dropdown to switch between them, labelled by their `title`.
Switching keeps your place, it navigates to the same page in the other version, or its index page when the page doesn't exist there:
| Page | Switching to 2.0.0 |
| -------------------------- | -------------------------- |
| `/docs/v1/getting-started` | `/docs/v2/getting-started` |
| `/docs/v1/legacy-api` | `/docs/v2`, the index page |
The type name (`"version"`) can be anything, it only identifies the type: root folders of the same
type under the same parent are interchangeable.
### Full Versioning [#full-versioning]
Sometimes you want to version the entire website, such as https://v14.fumadocs.dev (Fumadocs v14) and https://fumadocs.dev (Latest Fumadocs).
You can create a Git branch for a version of docs (call it `v2` for example), and deploy it as a separate app on another subdomain like `v2.my-site.com`.
Optionally, you can link to the other versions from your docs.
This design allows some advantages over partial versioning:
- Easy maintenance: Old docs/branches won't be affected when you iterate or upgrade dependencies.
- Better consistency: Not just the docs itself, your landing page (and other pages) will also be versioned.
# Fumadocs (Framework Mode): Page Slugs & Page Tree
URL: /docs/page-conventions
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/page-conventions.mdx
A shared convention for organizing your documents
> This guide only applies for content sources that uses `loader()` API, such as **Fumadocs MDX**.
## Overview [#overview]
Fumadocs generates **page slugs** and **page tree** (sidebar items) from your content directory using [`loader()`](/docs/headless/source-api),
the routing functionality will be handled by your React framework.
You can define folders and pages similar to file-system based routing.
To customize its output further, you may use [Loader Plugins](/docs/headless/source-api/plugins).
## File [#file]
For [MDX](https://mdxjs.com) & Markdown file, you can customize page information from frontmatter.
```mdx
---
title: My Page
description: Best document ever
icon: House
---
## Learn More
```
Fumadocs detects from the following properties to construct page trees.
| name | description |
| ------------- | ------------------------------------- |
| `title` | The title of page |
| `description` | The description of page |
| `icon` | The name of icon, see [Icons](#icons) |
Page information is supplied by the content source such as **Fumadocs MDX**.
On Fumadocs MDX, you can specify a [`schema`](/docs/mdx/collections#schema-1) option to customize frontmatter schema.
### Slugs [#slugs]
The slugs of a page are generated from its file path.
| path (relative to content folder) | slugs |
| --------------------------------- | ----------------- |
| `./dir/page.mdx` | `['dir', 'page']` |
| `./dir/index.mdx` | `['dir']` |
## Folder [#folder]
Organize multiple pages, you can create a [Meta file](#meta) to customize folders.
### Folder Group [#folder-group]
By default, putting a file into folder will change its slugs.
You can wrap the folder name in parentheses to avoid impacting the slugs of child files.
| path (relative to content folder) | slugs |
| --------------------------------- | ---------- |
| `./(group-name)/page.mdx` | `['page']` |
### Root Folder [#root-folder]
Marks the folder as a root folder, only items in the opened root folder will be visible.
```json title="meta.json"
{
"title": "Name of Folder",
"description": "The description of root folder (optional)",
"root": true
}
```
For example, when you are opening root folder `framework`, the other folders (e.g. `headless`) are not shown on the sidebar and other navigation elements.
Fumadocs UI renders root folders as [Layout Tabs](/docs/ui/layouts/docs#layout-tabs), which allows users to switch between them.
### Root Type [#root-type]
`root` also accepts a string, the **type** of root folder:
root folders of the same type under the same parent scope are interchangeable, such as versions of the same docs.
```json tab="v1/meta.json"
{
"title": "1.0.0",
"root": "version"
}
```
```json tab="v2/meta.json"
{
"title": "2.0.0",
"root": "version"
}
```
`root: true` is simply the default type, displayed as tabs.
Switching to another root folder of the same type maps a page to its **structural projection**, the page at the same path relative to the root folder:
| Page | Projection in `v2` |
| --------------------- | --------------------------------------------------- |
| `v1/guide.mdx` | `v2/guide.mdx` |
| `v1/python/guide.mdx` | `v2/python/guide.mdx`, nested root folders are kept |
Fumadocs UI renders a [dropdown](/docs/ui/layouts/docs#tabs-groups) for each root folder on the current page's path to switch between root folders of its type, see [Versioning](/docs/navigation#versioning) for a complete example.
## Meta [#meta]
Customize folders by creating a `meta.json` file in the folder.
```json title="meta.json"
{
"title": "Display Name",
"icon": "MyIcon",
"pages": ["index", "getting-started"],
"defaultOpen": true
}
```
| name | description |
| ------------- | -------------------------------------------- |
| `title` | Display name |
| `icon` | The name of icon, see [Icons](#icons) |
| `defaultOpen` | Open the folder by default |
| `collapsible` | Collapsible folder content (default: `true`) |
| `pages` | Folder items (see below) |
| `pagesIndex` | The index item (see below) |
### Pages [#pages]
Folder items are sorted alphabetically by default, you can add or control the order of items using `pages`.
```json title="meta.json"
{
"pages": ["index", "getting-started"]
}
```
> When specified, items are not included unless they are listed in `pages`.
| Type | Syntax | Description |
| ----------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Path** | `./path/to/page` | a path to page or folder. |
| **Separator** | `---Label---`
`---[Icon]Label---` | a separator between two sections (icon supported). | | **Link** | `[Text](url)`
`[Icon][Text](url)`
`external:[Text](url)` | insert links (icon supported)
add a `external:` prefix to mark links as external. | | **Rest** | `...` | include remaining pages (sorted alphabetically). | | **Reversed Rest** | `z...a` | reversed **Rest** item. | | **Extract** | `...folder` | extract the items from a folder. | | **Except** | `!item` | Exclude an item from `...` or `z...a`. | ```json title="meta.json" { "pages": [ "components", "---My Separator---", "...folder", "...", "!file", "!otherFolder", "[Vercel](https://vercel.com)", "[Triangle][Vercel](https://vercel.com)" ] } ```
The same page URL must not appear more than once in the entire page tree.
Duplicated page items are not allowed for the same reason.
This is intentional, such that Fumadocs can locate the active tree item purely based on current pathname.
### Folder Index [#folder-index]
When folder owns a index item, it becomes clickable and jumps to the index item when clicked.
By default, it is the `index` file under each folder. You can specify the index item of a folder, it accepts **Path** and **Link**.
```json tab="meta.json (Path)"
{
// assume there's a "overview.mdx" file under the folder
"pagesIndex": "overview"
}
```
```json tab="meta.json (Link)"
{
"pagesIndex": "[Example](https://example.com)"
}
```
## Icons [#icons]
Since Fumadocs doesn't include an icon library, you have to convert the icon names to JSX elements in runtime, and render it as a component.
You can add an [`icon` handler](/docs/headless/source-api#icons) to `loader()`.
## i18n Routing [#i18n-routing]
You can define different style for i18n routing.
```ts title="lib/i18n.ts"
import type { I18nConfig } from 'fumadocs-core/i18n';
export const i18n: I18nConfig = {
// default
parser: 'dot',
// or
parser: 'dir',
};
```
Add Markdown/meta files for different languages by attending `.{locale}` to your file name, like:
For the default locale, the locale code is optional.
All content files are grouped by language folders:
# Fumadocs (Framework Mode): Algolia
URL: /docs/search/algolia
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/algolia.mdx
Using Algolia with Fumadocs UI.
## Overview [#overview]
For the setup guide, see [Integrate Algolia Search](/docs/headless/search/algolia).
While generally we recommend building your own search with their client-side
SDK, you can also plug the built-in dialog interface.
## Setup [#setup]
Fumadocs CLI can set it up for you, it creates the search dialog, the `static.json` route and a script to sync the search index after each build:
```package-install
npx @fumadocs/cli feature search --provider algolia
```
Or manually:
Create a search dialog, replace `appId`, `apiKey` and `indexName` with your desired values.
```tsx title="components/search.tsx"
'use client';
import { liteClient } from 'algoliasearch/lite';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogFooter,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useAlgoliaSearch } from 'fumadocs-core/search/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
const appId = 'replace me';
const apiKey = 'replace me';
const algolia = liteClient(appId, apiKey);
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useAlgoliaSearch({
client: algolia,
indexName: 'document',
locale,
});
return (
Search powered by Algolia
);
}
```
`useAlgoliaSearch()` doesn't use instant search (their official
Javascript client).
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
### Tag Filter [#tag-filter]
Optionally, you can add UI for filtering results by tags. Configure [Tag Filter](/docs/headless/search/algolia#tag-filter) on search server and add the following:
```tsx
'use client';
import {
SearchDialog,
SearchDialogContent,
SearchDialogFooter,
SearchDialogOverlay,
type SharedProps,
TagsList,
TagsListItem,
} from 'fumadocs-ui/components/dialog/search';
import { useState } from 'react';
import { useFetchSearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const search = useFetchSearch({
tag, // [!code ++]
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs (Framework Mode): Custom Search
URL: /docs/search/custom
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/custom.mdx
For other search solutions.
## Overview [#overview]
Fumadocs is very flexible, you can integrate custom search with Fumadocs easily.
### Search Indexes [#search-indexes]
With Fumadocs MDX, the generated search indexes are exposed during runtime.
To expose search indexes statically, export the records with a pre-rendered `static.json` route, and process them with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
async function getDocuments() {
const documents = [];
for (const page of source.getPages()) {
documents.push({
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return documents;
}
export const revalidate = false;
export async function GET() {
return Response.json(await getDocuments());
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import type { StructuredData } from 'fumadocs-core/mdx-plugins';
interface DocumentRecord {
title: string;
description?: string;
url: string;
structured: StructuredData;
}
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
// sync the records to your search engine
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
async function getDocuments() {
const documents = [];
for (const page of source.getPages()) {
documents.push({
structured: await page.data.structuredData(),
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return documents;
}
export async function loader() {
return Response.json(await getDocuments());
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import type { StructuredData } from 'fumadocs-core/mdx-plugins';
interface DocumentRecord {
title: string;
description?: string;
url: string;
structured: StructuredData;
}
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
// sync the records to your search engine
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
async function getDocuments() {
const documents = [];
for (const page of source.getPages()) {
documents.push({
structured: await page.data.structuredData(),
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return documents;
}
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await getDocuments()),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import type { StructuredData } from 'fumadocs-core/mdx-plugins';
interface DocumentRecord {
title: string;
description?: string;
url: string;
structured: StructuredData;
}
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
// sync the records to your search engine
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
async function getDocuments() {
const documents = [];
for (const page of source.getPages()) {
documents.push({
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return documents;
}
export async function GET() {
return Response.json(await getDocuments());
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import type { StructuredData } from 'fumadocs-core/mdx-plugins';
interface DocumentRecord {
title: string;
description?: string;
url: string;
structured: StructuredData;
}
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
// sync the records to your search engine
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
The `structured` field contains the headings and paragraphs of each page, use it to generate accurate search indexes.
# Fumadocs (Framework Mode): FlexSearch
URL: /docs/search/flexsearch
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/flexsearch.mdx
A fast & minimal search engine.
## Overview [#overview]
For the setup guide, see [Integrate FlexSearch](/docs/headless/search/flexsearch).
It works through a API endpoint (running on server), or a statically cached JSON file for static websites.
## Setup [#setup]
Create a search dialog.
```tsx title="components/search.tsx"
'use client';
import { useFetchSearch } from 'fumadocs-core/search/client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
export default function DefaultSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useFetchSearch({
locale,
});
return (
);
}
```
For Static Export, you can configure [static mode](/docs/headless/search/flexsearch#static-export) on search server, and change the search client:
```tsx title="components/search.tsx"
'use client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useFlexsearchStatic } from 'fumadocs-core/search/client/flexsearch-static';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
export default function DefaultSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useFlexsearchStatic({ locale });
return (
);
}
```
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
### Tag Filter [#tag-filter]
Optionally, you can add UI for filtering results by tags. Configure [Tag Filter](/docs/headless/search/flexsearch#tag-filter) on search server and add the following:
```tsx
'use client';
import {
SearchDialog,
SearchDialogContent,
SearchDialogFooter,
SearchDialogOverlay,
type SharedProps,
TagsList,
TagsListItem,
} from 'fumadocs-ui/components/dialog/search';
import { useState } from 'react';
import { useFlexsearchStatic } from 'fumadocs-core/search/client/flexsearch-static';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const search = useFlexsearchStatic({
tag, // [!code ++]
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs (Framework Mode): Search
URL: /docs/search
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/index.mdx
Implement document search in your docs
## Search UI [#search-ui]
See [Search UI](/docs/ui/search) to learn how to customize the UI of document search.
## Search Client [#search-client]
You can choose & configure the search client according to your search engine, it defaults to ZBSearch.
=> {
const res = await fetch(`/api/my-search?${new URLSearchParams({ query, locale })}`);
return res.json();
},
[locale],
);
return experimental_useSearch(search);
}
```
### Community Integrations [#community-integrations]
A list of integrations maintained by community.
- [Trieve Search](/docs/headless/search/trieve)
- [Typesense Search](/docs/headless/search/typesense)
# Fumadocs (Framework Mode): Meilisearch
URL: /docs/search/meilisearch
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/meilisearch.mdx
Using Meilisearch with Fumadocs UI.
## Setup [#setup]
Fumadocs CLI can set it up for you, it creates the search dialog, the `static.json` route and a script to sync the search index after each build:
```package-install
npx @fumadocs/cli feature search --provider meilisearch
```
Or manually:
1. Integrate [Meilisearch](/docs/headless/search/meilisearch).
2. Create a search dialog, replace `host` and `apiKey` with your host URL and search API key.
```tsx title="components/search.tsx"
'use client';
import { Meilisearch } from 'meilisearch';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogFooter,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useMeilisearch } from 'fumadocs-core/search/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
const client = new Meilisearch({
host: 'replace me',
apiKey: 'replace me',
});
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useMeilisearch({
client,
indexName: 'docs',
locale,
});
return (
Search powered by Meilisearch
);
}
```
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
### Tag Filter [#tag-filter]
Optionally, you can add UI for filtering results by tags. Configure [Tag Filter](/docs/headless/search/meilisearch#tag-filter) on documents and add the following:
```tsx
'use client';
import {
SearchDialog,
SearchDialogContent,
SearchDialogFooter,
SearchDialogOverlay,
type SharedProps,
TagsList,
TagsListItem,
} from 'fumadocs-ui/components/dialog/search';
import { useState } from 'react';
import { useMeilisearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const search = useMeilisearch({
tag, // [!code ++]
// other options...
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs (Framework Mode): Mixedbread
URL: /docs/search/mixedbread
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/mixedbread.mdx
Using Mixedbread with Fumadocs UI.
## Setup [#setup]
Mixedbread search runs on your server at request time, it isn't available for static sites.
Fumadocs CLI can set it up for you, it creates the search dialog, the search route, the `static.json` route and a script to sync your store after each build:
```package-install
npx @fumadocs/cli feature search --provider mixedbread
```
Or manually:
1. Integrate [Mixedbread Search](/docs/headless/search/mixedbread).
2. Create a search dialog component.
```tsx title="components/search.tsx"
'use client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogFooter,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useFetchSearch } from 'fumadocs-core/search/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useFetchSearch({
api: '/api/search',
locale,
// every search is a request to Mixedbread
delayMs: 300,
});
return (
Search powered by Mixedbread
);
}
```
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
### Tag Filter [#tag-filter]
Optionally, you can add UI for filtering results by tags. Configure [Tag Filter](/docs/headless/search/mixedbread#tag-filter) on search server and add the following:
```tsx
'use client';
import {
SearchDialog,
SearchDialogContent,
SearchDialogFooter,
SearchDialogOverlay,
type SharedProps,
TagsList,
TagsListItem,
} from 'fumadocs-ui/components/dialog/search';
import { useState } from 'react';
import { useFetchSearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const search = useFetchSearch({
tag, // [!code ++]
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs (Framework Mode): Orama Cloud
URL: /docs/search/orama-cloud
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/orama-cloud.mdx
Using Orama Cloud with Fumadocs UI.
## Setup [#setup]
Fumadocs CLI can set it up for you, it creates the search dialog, the `static.json` route and a script to sync the search index after each build:
```package-install
npx @fumadocs/cli feature search --provider orama-cloud
```
Or manually:
1. Integrate [Orama Cloud](/docs/headless/search/orama-cloud).
2. Create a search dialog, replace `endpoint` and `api_key` with your desired values.
```tsx title="components/search.tsx"
'use client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogFooter,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useOramaCloudSearch } from 'fumadocs-core/search/client';
import { OramaCloud } from '@orama/core';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
const orama = new OramaCloud({
projectId: '',
apiKey: '',
});
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useOramaCloudSearch({
client: orama,
locale,
});
return (
Search powered by Orama
);
}
```
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
# Fumadocs (Framework Mode): ZBSearch (default)
URL: /docs/search/orama
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/orama.mdx
The default search engine powered by ZBSearch.
## Overview [#overview]
Fumadocs configures [ZBSearch search engine](/docs/headless/search/orama) out-of-the-box.
It works through a API endpoint (running on server), or a statically cached JSON file for static websites.
## Setup [#setup]
Create a search dialog.
The UI has been configured by default, you can also re-create it for further customizations:
```tsx title="components/search.tsx"
'use client';
import { useFetchSearch } from 'fumadocs-core/search/client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
export default function DefaultSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useFetchSearch({
locale,
});
return (
);
}
```
For Static Export, you can configure [static mode](/docs/headless/search/orama#static-export) on search server, and use the `static` client:
```tsx title="components/search.tsx"
'use client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useStaticSearch } from 'fumadocs-core/search/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
export default function DefaultSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const search = useStaticSearch({
locale,
});
return (
);
}
```
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
### Tag Filter [#tag-filter]
Optionally, you can add UI for filtering results by tags. Configure [Tag Filter](/docs/headless/search/orama#tag-filter) on search server and add the following:
```tsx
'use client';
import {
SearchDialog,
SearchDialogContent,
SearchDialogFooter,
SearchDialogOverlay,
type SharedProps,
TagsList,
TagsListItem,
} from 'fumadocs-ui/components/dialog/search';
import { useState } from 'react';
import { useFetchSearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const search = useFetchSearch({
tag, // [!code ++]
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs (Framework Mode): Typesense
URL: /docs/search/typesense
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/typesense.mdx
Using Typesense with Fumadocs UI.
> This is a community-maintained integration.
## Setup [#setup]
Fumadocs CLI can set it up for you, it creates the search dialog, the `static.json` route and a script to sync the search index after each build:
```package-install
npx @fumadocs/cli feature search --provider typesense
```
Or manually:
1. Integrate [Typesense Search](/docs/headless/search/typesense).
2. Create a search dialog component.
```tsx title="components/search.tsx"
'use client';
import {
SearchDialog,
SearchDialogClose,
SearchDialogContent,
SearchDialogFooter,
SearchDialogHeader,
SearchDialogIcon,
SearchDialogInput,
SearchDialogList,
SearchDialogOverlay,
type SharedProps,
} from 'fumadocs-ui/components/dialog/search';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
import { Client } from 'typesense';
import { useTypesenseSearch } from 'typesense-fumadocs-adapter/client';
const client = new Client({
nodes: [{ url: 'YOUR_TYPESENSE_SERVER_URL' }],
apiKey: 'YOUR_TYPESENSE_SEARCH_ONLY_API_KEY',
});
export default function TypesenseSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // optional
const { search, setSearch, query } = useTypesenseSearch({
typesenseCollectionName: 'docs',
locale,
legacy: false, // optional, set to true for fumadocs-ui version < 16.6.0
client,
});
return (
);
}
```
### Replace Search Dialog [#replace-search-dialog]
Replace the search dialog with yours from [`';
// [!code ++]
import SearchDialog from '@/components/search';
{children}
;
```
If it was in a server component, you would need a separate client component for provider to pass functions:
```tsx tab="provider.tsx"
'use client';
import { RootProvider } from 'fumadocs-ui/provider/';
import SearchDialog from '@/components/search';
import type { ReactNode } from 'react';
export function Provider({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
```tsx tab="app/layout.tsx"
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
### Tag Filter [#tag-filter]
Optionally, you can add UI for filtering results by tags. Configure [Tag Filter](/docs/headless/search/typesense#tag-filter) on search server and add the following:
```tsx
'use client';
import {
SearchDialog,
SearchDialogContent,
SearchDialogFooter,
SearchDialogOverlay,
type SharedProps,
TagsList,
TagsListItem,
} from 'fumadocs-ui/components/dialog/search';
import { useState } from 'react';
import { useTypesenseSearch } from 'typesense-fumadocs-adapter/client';
export default function TypesenseSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const { search, setSearch, query } = useTypesenseSearch({
tag, // [!code ++]
// other options...
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs (Framework Mode): What is Fumadocs
URL: /docs/what-is-fumadocs
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/what-is-fumadocs.mdx
Introducing Fumadocs, a docs framework that you can break.
The **Fumadocs** framework refers to a combination of UI + Core + Content Source, Fumadocs is more of a mental framework and each layer can be a library on its own.
## Philosophy [#philosophy]
Fumadocs was created to bring a more customisable experience for building docs, to be a docs framework that is not opinionated, **a "framework" that you can break**.
### Less Abstraction [#less-abstraction]
While most frameworks are configured with a configuration file, they usually lack flexibility when you hope to tune its details.
You can’t control how they render the page nor the internal logic.
Fumadocs expects you to write code and cooperate with the rest of your software, it shows you how the app works and fully customisable, instead of a configuration file.
### Seamless Integration [#seamless-integration]
Fumadocs integrates tightly with your React framework, bringing useful utilities and a good-looking UI.
For Next.js developers, you are still using features of App Router, like **Static Site Generation**. There is nothing new for Next.js developers, that everything is familiar to you.
### Composable UI [#composable-ui]
The only thing Fumadocs UI (the default theme) offers is **User Interface**. The UI is opinionated for bringing better mobile responsiveness and user experience.
Instead, we follow a much more flexible approach inspired by Shadcn UI — [Fumadocs CLI](/docs/cli), allowing you to "fork" a part of Fumadocs UI, and fully customize it.
### Server-first Approach [#server-first-approach]
Traditionally, static site generators are **static**.
However, Fumadocs introduce a server-first approach powered by React Server Component.
With perfect server-client boundary, content becomes dynamic and interactive.
You can fetch data from server to display content, or integrate with CMS receiving realtime updates. It is always up-to-date and easy to maintain.
### Minimal [#minimal]
Fumadocs is maintained by Fuma and many contributors, with care on the maintainability of codebase.
While we don't aim to offer every functionality people wanted, we're more focused on making basic features perfect and well-maintained.
You can also help Fumadocs to be more useful by contributing!
## When to use Fumadocs [#when-to-use-fumadocs]
Fumadocs is designed with flexibility in mind, it is not limited to certain usages.
- `fumadocs-core` is a headless UI library for building docs.
- `fumadocs-mdx` is a useful library to handle MDX content.
For most of the web applications, vanilla React.js is no longer enough.
Nowadays, we also wish to have a blog, a showcase page, a FAQ page, etc. In these cases, Fumadocs can help you build the
docs easier, with less boilerplate.
You can read [Comparisons](/docs/comparisons) if you're interested.
### Documentation [#documentation]
Fumadocs focuses on **authoring experience**, it provides a beautiful theme and many docs automation tools.
It helps you to iterate your codebase faster while never leaving your docs behind.
You can take this site as an example of docs site built with Fumadocs.
### Blog sites [#blog-sites]
Most React.js frameworks can already suffice the needs of a blog site.
Fumadocs provides additional tooling, including syntax highlighting, document search, and a default theme (Fumadocs UI).
It helps you to avoid reinventing the wheels.
# Fumadocs (Framework Mode): Scalar Example
URL: /docs/asyncapi
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/asyncapi/index.mdx
View the Scalar Galaxy example AsyncAPI schema.
# Fumadocs CLI (the CLI tool for automating Fumadocs apps): create-fumadocs-app
URL: /docs/cli/create-fumadocs-app
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/cli/create-fumadocs-app.mdx
The CLI to create new Fumadocs apps
## Usage [#usage]
```npm
npx create-fumadocs-app@latest my-docs
```
It asks for the template and features to configure, you can also pass them as options.
### Options [#options]
| Option | Description |
| ------------------- | ----------------------------------------------------------------------------------------- |
| `--template ` | The template to use, see [Templates](#templates). |
| `--src` | (Next.js only) Use the `src/` directory. |
| `--linter ` | Configure a linter: `eslint` (Next.js only), `oxlint` or `biome`. |
| `--search ` | Search solution: `orama` (default, local search) or `orama-cloud`. |
| `--og-image ` | OG image: `next-og` (Next.js only) or `takumi`, others use Takumi. |
| `--ai-chat ` | AI chat: `openrouter`, `llmgateway` or `inkeep`, not available on static & SPA templates. |
| `--install` | Install dependencies automatically. |
| `--no-git` | Skip Git repository initialization. |
| `--pm ` | Package manager: `npm`, `pnpm`, `yarn` or `bun`, detected from how the CLI is invoked. |
| `-y, --yes` | Skip prompts, use defaults for options not specified. |
### Templates [#templates]
| Value | Description |
| ---------------------------- | ------------------------------------------ |
| `+next+fuma-docs-mdx` | Next.js (default) |
| `+next+fuma-docs-mdx+static` | Next.js with static export |
| `waku` | Waku |
| `react-router` | React Router |
| `react-router-spa` | React Router in SPA mode |
| `tanstack-start` | Tanstack Start |
| `tanstack-start-spa` | Tanstack Start in SPA mode |
| `astro` | Astro with React islands (partial support) |
### Non-interactive [#non-interactive]
Pass `--yes` to skip prompts, useful for scripts, CI and AI agents:
```npm
npx create-fumadocs-app@latest my-docs --template +next+fuma-docs-mdx --install --yes
```
Options you didn't specify use their defaults: no linter, local search, no AI chat. It fails when the target directory already exists and is not empty.
## Programmatic API [#programmatic-api]
Despite the classical CLI usage, you can also use it in scripts like:
```npm
npm install create-fumadocs-app
```
```ts
import { create } from 'create-fumadocs-app';
await create({
outputDir: 'my-app',
template: '+next+fuma-docs-mdx',
packageManager: 'pnpm',
});
```
# Fumadocs CLI (the CLI tool for automating Fumadocs apps): User Guide
URL: /docs/cli
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/cli/index.mdx
The CLI tool that automates setups and installs components.
## Installation [#installation]
Initialize a config for CLI:
```package-install
npx @fumadocs/cli
```
You can change the output paths of components in the config.
### Init [#init]
Set up Fumadocs on an existing app, it supports Next.js, React Router, Tanstack Start and Waku.
```package-install
npx @fumadocs/cli init
```
To avoid conflicts with your app, the docs pages are added in a dedicated route group (e.g. `app/(docs)` on Next.js) with their own provider and layout, route handlers like the search API follow the [examples](https://github.com/fuma-nama/fumadocs/tree/dev/examples). Only a few edits are made to existing files:
- Fumadocs MDX plugin in your framework config.
- Fumadocs UI styles in your global CSS.
- `suppressHydrationWarning` on the `` element of your root layout, for the theme switch.
- `.source` in `.gitignore`.
Pass `--i18n` to set up [internationalization](/docs/internationalization): the docs routes get a locale segment (optional for the default locale where the router supports it), a `lib/i18n.ts` config and, on Next.js, a proxy scoped to the docs routes. Other features follow the i18n config of your project.
It asks before overwriting a file, pass `--yes` to skip prompts and `--no-install` to only write dependencies to `package.json`.
### Features [#features]
Configure a feature on your project, it installs the needed components & routes, and wires them into your app.
```package-install
npx @fumadocs/cli feature ai --provider openrouter
```
| Feature | Description |
| ---------- | ------------------------------------------------------------------------------------------ |
| `docs` | Set up Fumadocs, same as `init`. |
| `ai` | [Ask AI](/docs/integrations/llms#ask-ai) dialog, `--provider`. |
| `llms` | [LLM routes](/docs/integrations/llms): `llms.txt`, `llms-full.txt` and per-page Markdown. |
| `mcp` | [MCP server](/docs/integrations/llms#mcp-server) to search and read the docs. |
| `webmcp` | [WebMCP](/docs/integrations/llms#webmcp) tools for AI agents in the browser, experimental. |
| `og` | Open Graph image generation with Takumi or next/og (Next.js only), `--engine`. |
| `search` | 3rd party [search solution](/docs/search), `--provider`. |
| `feedback` | [Feedback](/docs/integrations/feedback) component on docs pages. |
| `epub` | Route to [export EPUB](/docs/guides/export-epub). |
| `lint` | Configure ESLint (Next.js only), Biome or Oxlint, `--linter`. |
Features adapt to your setup:
- Fumadocs MDX with the [Macro API](/docs/mdx/macro) or a `source.config.ts`, other content sources can't use `llms`, `mcp` and `epub`.
- The `baseUrl` of your docs, `src/` directory, `next.config.ts`, i18n, static export and SPA modes.
- React Router with file-based routes: the routes to register are printed instead.
The paths of routes are placed under the constants of `lib/shared.ts`.
See help for the available options:
```package-install
npx @fumadocs/cli feature -h
```
### Components [#components]
Select and install components.
```package-install
npx @fumadocs/cli add
```
You can pass component names directly.
```package-install
npx @fumadocs/cli add banner files
```
#### How the magic works? [#how-the-magic-works]
The CLI fetches the latest version of component from the GitHub repository of Fumadocs.
When you install a component, it is guaranteed to be up-to-date.
In addition, it also transforms import paths.
Make sure to use the latest version of CLI
> This is highly inspired by Shadcn UI.
### Customize [#customize]
A simple way to customize Fumadocs layouts.
```package-install
npx @fumadocs/cli customize
```
It installs the layout into `layouts` and points the imports of your route files at it.
### Shadcn UI [#shadcn-ui]
On projects with a `components.json`, the CLI follows the aliases of Shadcn UI and:
- installs the `shadcn` preset, so Fumadocs UI adopts your theme colors.
- reuses the `button`, `popover` and `collapsible` in your `ui` directory, they share the API of Shadcn UI.
- imports `cn` from your `utils` alias.
Fumadocs' copies are only installed when you don't have them yet.
### Tree [#tree]
Generate files tree for Fumadocs UI `Files` component, using the `tree` command from your terminal.
```package-install
npx @fumadocs/cli tree ./my-dir ./output.tsx
```
You can output MDX files too:
```package-install
npx @fumadocs/cli tree ./my-dir ./output.mdx
```
See help for further details:
```package-install
npx @fumadocs/cli tree -h
```
#### Example Output [#example-output]
```tsx title="output.tsx"
import { File, Folder, Files } from 'fumadocs-ui/components/files';
export default (
);
```
# Fumadocs CLI (the CLI tool for automating Fumadocs apps): Preview
URL: /docs/cli/preview
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/cli/preview.mdx
A light tool to view Markdown files.
## Introduction [#introduction]
`fumadocs-preview` allows you to view Markdown files with Fumadocs, it is useful for reading skills files & notes.
Run the command under your project directory.
```npm
npx fumadocs-preview dir/to/content
```
### Configurations [#configurations]
For other configurations, you can install it locally:
```npm
npm install fumadocs-preview -D
```
Then init the config file:
```npm
npx fumadocs-preview init
```
# Fumadocs (Framework Mode): Store Example
URL: /docs/graphql
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/graphql/index.mdx
View the example store GraphQL schema.
# Fumadocs Core (the core library of Fumadocs): Breadcrumb
URL: /docs/headless/components/breadcrumb
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/components/breadcrumb.mdx
The navigation component at the top of the screen
A hook for implementing Breadcrumb in your documentation. It returns breadcrumb items for a page based on the given page tree.
> If present, the index page of a folder will be used as the item.
## Usage [#usage]
It exports a `useBreadcrumb` hook:
```ts twoslash
declare const tree: any;
import { usePathname } from 'next/navigation';
// ---cut---
import { useBreadcrumb } from 'fumadocs-core/breadcrumb';
// obtain `pathname` using the hook provided by your React framework.
const pathname = usePathname();
const items = useBreadcrumb(pathname, tree);
// ^?
```
### Example [#example]
A styled example for Next.js.
```tsx
'use client';
import { usePathname } from 'next/navigation';
import { useBreadcrumb } from 'fumadocs-core/breadcrumb';
import type { PageTree } from 'fumadocs-core/page-tree';
import { Fragment } from 'react';
import { ChevronRight } from 'lucide-react';
import Link from 'next/link';
export function Breadcrumb({ tree }: { tree: PageTree.Root }) {
const pathname = usePathname();
const items = useBreadcrumb(pathname, tree);
if (items.length === 0) return null;
return (
Click Me
```
# Fumadocs Core (the core library of Fumadocs): TOC
URL: /docs/headless/components/toc
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/components/toc.mdx
Table of Contents
A Table of Contents with active anchor observer and auto scroll.
## Usage [#usage]
```tsx
import * as Base from 'fumadocs-core/toc';
return (
);
```
### Anchor Provider [#anchor-provider]
Watches for the active anchor using the Intersection Observer API.
### AnchorProviderProps
| Prop | Type | Description |
| ----------- | ----------- | ---------------------------------------------------- |
| `toc` | `array` | |
| `single?` | `union` | Only accept one active item at most Default: `false` |
| `children?` | `ReactNode` | |
### Scroll Provider [#scroll-provider]
Scrolls the scroll container to the active anchor.
### ScrollProviderProps
| Prop | Type | Description |
| -------------- | ----------- | --------------------------------------------- |
| `containerRef` | `object` | Scroll into the view of container when active |
| `children?` | `ReactNode` | |
### TOC Item [#toc-item]
An anchor item for jumping to the target anchor.
| Data Attribute | Values | Description |
| -------------- | ------------- | -------------------- |
| `data-active` | `true, false` | Is the anchor active |
## Example [#example]
```tsx
import { AnchorProvider, ScrollProvider, TOCItem, type TOCItemType } from 'fumadocs-core/toc';
import { type ReactNode, useRef } from 'react';
export function Page({ items, children }: { items: TOCItemType[]; children: ReactNode }) {
const viewRef = useRef(null);
return (
{items.map((item) => (
{item.title}
))}
{children}
);
}
```
# Fumadocs Core (the core library of Fumadocs): Content Collections
URL: /docs/headless/content-collections
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/content-collections/index.mdx
Use Content Collections for Fumadocs
[Content Collections](https://www.content-collections.dev) is a library that transforms your content into type-safe data collections.
## Setup [#setup]
Follow their [official guide](https://content-collections.dev/docs) to setup Content Collections for your React framework.
Make sure you have MDX configured:
```npm
npm i @content-collections/mdx
```
To integrate with Fumadocs, add the following to your `content-collections.ts`.
```ts title="content-collections.ts"
import { defineCollection, defineConfig } from '@content-collections/core';
import { transformMDX } from '@fumadocs/content-collections/configuration';
import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
const docs = defineCollection({
name: 'docs',
directory: 'content/docs',
include: '**/*.mdx',
schema: pageSchema,
transform: transformMDX,
});
const metas = defineCollection({
name: 'meta',
directory: 'content/docs',
include: '**/meta.json',
parser: 'json',
schema: metaSchema,
});
export default defineConfig({
collections: [docs, metas],
});
```
And pass it to `loader()`.
```ts title="lib/source.ts"
import { allDocs, allMetas } from 'content-collections';
import { loader } from 'fumadocs-core/source';
import { createMDXSource } from '@fumadocs/content-collections';
export const source = loader({
baseUrl: '/docs',
source: createMDXSource(allDocs, allMetas),
});
```
Done! You can access the pages and generated page tree from Source API.
```ts
import { getPage } from '@/lib/source';
const page = getPage(slugs);
// MDX output
page?.data.body;
// Table of contents
page?.data.toc;
// Structured Data, for Search API
page?.data.structuredData;
```
### MDX Options [#mdx-options]
You can customize MDX options in the `transformMDX` function.
```ts
import { defineCollection } from '@content-collections/core';
import { transformMDX } from '@fumadocs/content-collections/configuration';
const docs = defineCollection({
transform: (document, context) =>
transformMDX(document, context, {
// options here
}),
});
```
### Import Components [#import-components]
To use components from other packages like Fumadocs UI, pass them to your `
Content Collections uses `mdx-bundler` to bundle MDX files.
To support importing a package from node modules, Fumadocs added a default value to the `cwd` option of MDX Bundler.
It works good, but we still **do not** recommend importing components in MDX files.
Reasons:
- It requires esbuild to bundle these components, while it should be done by the framework's bundler (e.g. Vite or Turbopack)
- You can refactor the import path of components without changing your MDX files.
- With Remote Sources, it doesn't make sense to add an import in MDX files.
# Fumadocs Core (the core library of Fumadocs): Introduction
URL: /docs/headless
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/index.mdx
Getting started with core library
## What is this? [#what-is-this]
Fumadocs Core offers server-side functions and headless components to build docs on React.js frameworks like Next.js, Waku, and Astro with React islands.
- [Search](/docs/headless/search)
- Breadcrumb, Sidebar, TOC Components
- Remark/Rehype Plugins
- [MCP tools](/docs/headless/utils/mcp) for AI agents to search and read docs
- [Additional utilities](/docs/headless/utils)
It can be used without Fumadocs UI, in other words, it's headless.
For beginners and normal usages, use [Fumadocs UI](/docs/ui).
## Installation [#installation]
Install the core package. Individual integrations may require additional dependencies, listed in their guides.
```package-install
fumadocs-core
```
For some components, a framework provider is needed:
```tsx tab="Next.js"
import type { ReactNode } from 'react';
import { NextProvider } from 'fumadocs-core/framework/next';
export function RootLayout({ children }: { children: ReactNode }) {
// or if you're using Fumadocs UI, use `{children} ;
}
```
```tsx tab="React Router"
import type { ReactNode } from 'react';
import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
export function Root({ children }: { children: ReactNode }) {
return {children} ;
}
```
```tsx tab="Tanstack Start/Router"
import type { ReactNode } from 'react';
import { TanstackProvider } from 'fumadocs-core/framework/tanstack';
export function Root({ children }: { children: ReactNode }) {
return {children} ;
}
```
```tsx tab="Waku"
import type { ReactNode } from 'react';
import { WakuProvider } from 'fumadocs-core/framework/waku';
export function Root({ children }: { children: ReactNode }) {
return {children} ;
}
```
```tsx tab="Astro"
import type { ReactNode } from 'react';
import { AstroProvider } from 'fumadocs-core/framework/astro';
export function DocsIsland({
children,
pathname,
params,
}: {
children: ReactNode;
pathname: string;
params: Record;
}) {
return (
{children}
);
}
```
Explore the APIs and components:
# Fumadocs Core (the core library of Fumadocs): Configuration
URL: /docs/headless/internationalization/config
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/internationalization/config.mdx
Shared i18n configuration
For framework integration guide, see [Internationalization](/docs/internationalization).
## Define Config [#define-config]
Fumadocs core provides necessary middleware and utilities for i18n support.
You can define a config to share between utilities.
```ts title="lib/i18n.ts"
import { defineI18n } from 'fumadocs-core/i18n';
export const i18n = defineI18n({
defaultLanguage: 'en',
languages: ['en', 'cn'],
});
```
### Hide Locale Prefix [#hide-locale-prefix]
To hide the locale prefix (e.g. `/en/page` -> `/page`), use the `hideLocale` option.
```ts
import { defineI18n } from 'fumadocs-core/i18n';
export const i18n = defineI18n({
defaultLanguage: 'en',
languages: ['en', 'cn'],
hideLocale: 'default-locale',
});
```
| Mode | Description |
| ---------------- | -------------------------------------------------- |
| `always` | Always hide the prefix, detect locale from cookies |
| `default-locale` | Only hide the default locale |
| `never` | Never hide the prefix (default) |
Using
### Fallback Language [#fallback-language]
The fallback language to use when translations are missing for a file, default to your `defaultLanguage`.
It accepts one of the languages in your `languages` array.
```ts
import { defineI18n } from 'fumadocs-core/i18n';
export const i18n = defineI18n({
languages: ['en', 'cn'],
defaultLanguage: 'en',
// Chinese variant is used if a file is missing in English
fallbackLanguage: 'cn',
});
```
To disable the fallback behaviour, set it to `null`:
```ts
import { defineI18n } from 'fumadocs-core/i18n';
export const i18n = defineI18n({
languages: ['en', 'cn'],
defaultLanguage: 'en',
fallbackLanguage: null,
});
```
When disabled, no fallback will be used (including `meta.json`). You can still create a shared file for every locale with `$`:
# Fumadocs Core (the core library of Fumadocs): Middleware
URL: /docs/headless/internationalization/middleware
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/internationalization/middleware.mdx
Next.js proxy for implementing i18n routing
## Setup [#setup]
Redirects users to appropriate locale, it can be customized from `i18n.ts` config file.
```ts title="proxy.ts"
import { createI18nMiddleware } from 'fumadocs-core/i18n/middleware';
import { i18n } from '@/lib/i18n';
export default createI18nMiddleware(i18n);
export const config = {
// Matcher ignoring `/_next/` and `/api/`
// You may need to adjust it to ignore static assets in `/public` folder
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
};
```
> When `hideLocale` is enabled, it uses `NextResponse.rewrite` to hide locale prefixes.
# Fumadocs Core (the core library of Fumadocs): Headings
URL: /docs/headless/mdx/headings
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/headings.mdx
Process headings from your document
## Remark Heading [#remark-heading]
Applies ids to headings.
```ts title="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkHeading } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [remarkHeading],
});
```
> This plugin is included by default on Fumadocs MDX.
### Extract TOC [#extract-toc]
By default, it extracts the headings (table of contents) of a document to `vfile.data.toc`.
You can disable it with:
```ts
import { remarkHeading } from 'fumadocs-core/mdx-plugins';
export default {
remarkPlugins: [[remarkHeading, { generateToc: false }]],
};
```
### Custom Ids [#custom-heading-id]
You can customize the heading id with `[#slug]`.
```md
# heading [#slug]
```
### Output [#output]
An array of `TOCItemType`.
### TOCItemType
| Prop | Type | Description |
| -------- | ----------- | ------------------------------ |
| `title` | `ReactNode` | |
| `url` | `string` | |
| `depth` | `number` | |
| `_step?` | `number` | [remark-steps] the step number |
## Rehype TOC [#rehype-toc]
Exports table of contents (an array of `TOCItemType`), it allows JSX nodes which is not possible with a Remark plugin.
> It requires MDX.js.
### Usage [#usage]
```ts
import { rehypeToc } from 'fumadocs-core/mdx-plugins';
export default {
rehypePlugins: [rehypeToc],
};
```
### Output [#output-1]
For a Markdown document:
```md
## Hello `code`
```
An export will be created:
```jsx
export const toc = [
{
title: (
<>
Hello
For Fumadocs MDX, it is now enabled by default.
You can use the [`remarkNpm`](/docs/headless/mdx/remark-npm) plugin instead.
## Usage [#usage]
```package-install
fumadocs-docgen
```
Add the remark plugin.
```ts title="source.config.ts" tab="Fumadocs MDX"
import { remarkInstall } from 'fumadocs-docgen';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkInstall],
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkInstall } from 'fumadocs-docgen';
await compile('...', {
remarkPlugins: [remarkInstall],
});
```
Define the required components.
```tsx title="components/mdx.tsx (Fumadocs UI)"
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import defaultComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultComponents,
// [!code ++:2]
Tab,
Tabs,
...components,
} satisfies MDXComponents;
}
```
| Component | |
| --------- | ---------------------------------- |
| Tabs | Accepts an array of item (`items`) |
| Tab | Accepts the name of item (`value`) |
Create code blocks with `package-install` as language.
````mdx
```package-install
my-package
```
```package-install
npm i my-package -D
```
````
### Output [#output]
The following structure should be generated by the plugin.
```mdx
...
...
...
...
```
```package-install
my-package
```
## Options [#options]
### Persistent [#persistent]
When using with Fumadocs UI, you can enable persistence with the `persist` option.
```ts title="source.config.ts" tab="Fumadocs MDX"
import { remarkInstall } from 'fumadocs-docgen';
import { defineConfig } from 'fumadocs-mdx/config';
const remarkInstallOptions = {
persist: {
id: 'some-id',
},
};
export default defineConfig({
mdxOptions: {
remarkPlugins: [[remarkInstall, remarkInstallOptions]],
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkInstall } from 'fumadocs-docgen';
const remarkInstallOptions = {
persist: {
id: 'some-id',
},
};
await compile('...', {
remarkPlugins: [[remarkInstall, remarkInstallOptions]],
});
```
This will instead generate:
```mdx
...
```
# Fumadocs Core (the core library of Fumadocs): Rehype Code
URL: /docs/headless/mdx/rehype-code
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/rehype-code.mdx
Code syntax highlighter
A wrapper of [`@shikijs/rehype`](https://shiki.style/packages/rehype), the syntax highlighter used by Fumadocs.
It converts raw `` codeblocks into highlighted codeblocks:
````md tab="Input"
```ts
console.log('Hello World');
```
````
```html tab="Output"
This is a `title`
Hello World
Hello World
```
### When to use [#when-to-use]
We highly recommend using the JSX syntax of MDX instead.
It's more flexible, some editors support IntelliSense in MDX files.
```mdx
Hello World
```
# Fumadocs Core (the core library of Fumadocs): Remark Image
URL: /docs/headless/mdx/remark-image
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-image.mdx
Adding size attributes to images.
This plugin adds `width` and `height` attributes to your image elements, which is needed for Image Optimization on Next.js and some other frameworks.
## Usage [#usage]
Add it to your Remark plugins.
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [remarkImage],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
// it is enabled by default, customize it here
},
},
});
```
Supported:
- Local Images
- External URLs
- Next.js static imports
### How It Works [#how-it-works]
For Next.js, it uses **static imports** to import local images, which supports the `placeholder` option of Next.js Image.
Next.js can handle image imports with its built-in image loader.
Otherwise, it uses the file system or an HTTP request to download the image and obtain its size.
### Options [#options]
### RemarkImageOptions
| Prop | Type | Description |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicDir?` | `string` | Directory or base URL to resolve absolute image paths |
| `placeholder?` | `union` | Preferred placeholder type, only available with `useImport` + local images. Default: `'none'` |
| `onError?` | `union` | Define how to handle errors when fetching image size. - `error` (default): throw an error. - `ignore`: do absolutely nothing (Next.js Image component may complain). - `hide`: remove that image element. Default: `'error'` |
| `useImport?` | `union` | Import images in the file, and let bundlers handle it. ```tsx import MyImage from "./public/img.png"; 
``` When disabled, `placeholder` will be ignored. Default: `true` |
| `external?` | `union` | Fetch image size of external URLs Default: `true` |
### Example: With Imports [#example-with-imports]
```mdx
```
Yields:
```mdx
import HelloImage from './public/hello.png';
```
Where `./public/hello.png` points to the image in public directory.
### Example: Without Imports [#example-without-imports]
For Next.js, you can disable static imports on local images.
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [[remarkImage, { useImport: false }]],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
useImport: false,
},
},
});
```
```mdx
```
Yields:
```mdx
```
### Example: Relative Paths [#example-relative-paths]
When `useImport` is enabled, you can reference local images using relative paths.
```mdx
```
Be careful that using it with `useImport` disabled **doesn't work**.
Next.js will not add the image to public assets unless you have imported it in code.
For images in public directory, you can just reference them without relative paths.
### Example: Public Directory [#example-public-directory]
Customize the path of public directory
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
import path from 'node:path';
await compile('...', {
remarkPlugins: [[remarkImage, { publicDir: path.join(process.cwd(), 'dir') }]],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
import path from 'node:path';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
publicDir: path.join(process.cwd(), 'dir'),
},
},
});
```
You can pass a URL too.
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [[remarkImage, { publicDir: 'https://my-cdn.com/images' }]],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
publicDir: 'https://my-cdn.com/images',
},
},
});
```
# Fumadocs Core (the core library of Fumadocs): Remark LLMs
URL: /docs/headless/mdx/remark-llms
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-llms.mdx
Export the Markdown of your documents for LLMs.
The `remarkLLMs` plugin exports the Markdown of a document as `_markdown`, for LLMs. It keeps the Markdown you wrote, see [Stringification](/docs/headless/mdx/stringification) for how it's generated.
```mdx tab="Input"
import { Callout } from 'fumadocs-ui/components/callout';
## Getting Started
Hello **world**.
```
```md tab="Output"
## Getting Started [#getting-started]
Hello **world**.
```
ESM is removed, headings get their IDs (see `headingIds`), and included content is expanded with Fumadocs MDX.
## Usage [#usage]
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineDocs } from 'fumadocs-mdx/config';
export default defineDocs({
docs: {
postprocess: {
// `true`, or the options of `remarkLLMs`
includeProcessedMarkdown: true,
},
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkLLMs } from 'fumadocs-core/mdx-plugins/remark-llms';
await compile('...', {
remarkPlugins: [remarkLLMs],
});
```
With Fumadocs MDX, read it from your pages:
```ts
const markdown = await page.data.getText('processed');
```
## JSX Elements [#jsx-elements]
JSX elements are kept as you wrote them. To change them:
| Option | Elements |
| -------------------- | --------------------------------------------- |
| `filterElement` | Removed, or replaced by their children |
| `mdxAsPlaceholder` | Turned into placeholders, rendered at runtime |
| `output: 'function'` | Rendered by their components, into Markdown |
### Placeholders [#placeholders]
List the components to output as placeholders:
```ts
import type { LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
mdxAsPlaceholder: ['Callout'],
};
```
Then render them, from runtime data if needed:
```ts
import { renderPlaceholder } from 'fumadocs-core/mdx-plugins/remark-llms.runtime';
const markdown = await renderPlaceholder(await page.data.getText('processed'), {
// `children` is the Markdown of its content
Callout: ({ attributes, children }) => `> **${attributes.title}**\n>\n> ${children}`,
});
```
### Function Output [#output]
With `output: 'function'`, `_markdown` is a component: Markdown stays as you wrote it, JSX elements are rendered by your components.
```ts
import type { LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
output: 'function',
};
```
Render it with your components:
```tsx tab="Fumadocs MDX"
import { getMDXComponents } from '@/components/mdx';
const markdown = await page.data.getText('processed', {
components: getMDXComponents(),
});
```
```tsx tab="MDX Compiler"
import { renderToMarkdown } from 'fumadocs-core/server';
import { getMDXComponents } from '@/components/mdx';
import { _markdown as Markdown } from './page.mdx';
const markdown = await renderToMarkdown(
```
## Setup [#setup]
Add the remark plugin:
```tsx tab="Fumadocs MDX" title="source.config.ts"
import { remarkMdxFiles } from 'fumadocs-core/mdx-plugins';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkMdxFiles],
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkMdxFiles } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [remarkMdxFiles],
});
```
And make sure you have defined `
npm
pnpm
yarn
bun
...
...
...
...
```
```npm
npm i my-package
```
### Persistent [#persistent]
When using with Fumadocs UI, you can enable persist the selected value with the `persist` option.
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkNpmOptions: {
persist: {
id: 'package-manager',
},
},
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkNpm, type RemarkNpmOptions } from 'fumadocs-core/mdx-plugins';
const remarkNpmOptions: RemarkNpmOptions = {
persist: {
id: 'package-manager',
},
};
await compile('...', {
remarkPlugins: [[remarkNpm, remarkNpmOptions]],
});
```
This will generate a [`persist`](/docs/ui/components/tabs#persistent) prop to `![]()
` element, the output keeps ``.
## Editing the Output [#editing-the-output]
A plugin replacing authored content records the Markdown of its node with `replaceSource()`:
```ts title="remark-note.ts"
import type { Root } from 'mdast';
import type { VFile } from 'vfile';
import { visit } from 'unist-util-visit';
import { replaceSource } from 'fumadocs-core/mdx-plugins/stringifier';
export function remarkNote() {
return (tree: Root, file: VFile) => {
visit(tree, 'mdxJsxFlowElement', (node) => {
if (node.name !== 'Note') return;
replaceSource(file, node, (s) => `**Note:**\n\n${s.inner(node)}`);
// transform the node for rendering...
});
};
}
```
- A string replaces the node, along with the edits inside it.
- A function runs after every plugin. `s.stringify(node)` and `s.inner(node)` (its children) give their Markdown, with the edits inside.
- When a node is edited more than once, the last edit wins.
To edit a namespace only, like `search` for the records of Remark Structure, pass it as the last argument:
```ts
// the Markdown for LLMs keeps the tag, search records don't
replaceSource(file, node, (s) => s.stringify(node).replace(' [step]', ''), 'search');
```
For search, a plugin adds the records of its nodes with [`data.structuredData`](/docs/headless/mdx/structure#plugins).
## Embedded Content [#embedded-content]
Nodes parsed from another source, like an [included file](/docs/mdx/include), have positions in that source. Embed them with `embedSource()` to stringify them like your own content:
```ts
import { embedSource } from 'fumadocs-core/mdx-plugins/stringifier';
// replaces `node` with the nodes parsed from `otherSource`
embedSource(file, node, otherSource, otherTree.children);
```
Other nodes parsed from a string must not keep their `position`, it doesn't point into your document.
The Sätteri compiler of Fumadocs MDX works the same way, with its own versions of these plugins.
# Fumadocs Core (the core library of Fumadocs): Remark Structure
URL: /docs/headless/mdx/structure
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/structure.mdx
Extract search records from your documents.
The `remarkStructure` plugin extracts the headings and contents of a document as records for [search](/docs/headless/search). Records keep the Markdown you wrote, see [Stringification](/docs/headless/mdx/stringification) for how it's generated.
```mdx tab="Input"
## Installation
Run the [command](/docs/cli) below.
Restart the **server** after it.
| Option | Default |
| ------ | ------- |
| `dir` | `docs` |
```
```json tab="Output"
{
"headings": [{ "id": "installation", "content": "Installation" }],
"contents": [
{ "heading": "installation", "content": "Run the command below." },
{ "heading": "installation", "content": "Restart the **server** after it. " },
{
"heading": "installation",
"content": "| Option | Default |\n| --- | --- |\n| `dir` | `docs` |",
"table": "table-0"
}
]
}
```
## Usage [#usage]
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
// enabled by default, exported as `structuredData`
remarkStructureOptions: {},
},
});
```
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkStructure } from 'fumadocs-core/mdx-plugins';
const file = await compile('...', {
// `exportAs` exports it from the document too
remarkPlugins: [[remarkStructure, { exportAs: 'structuredData' }]],
});
console.log(file.data.structuredData);
```
## Records [#records]
Headings, paragraphs, blockquotes, tables and JSX elements are recorded (see `types`):
- Links are replaced by their text, images are removed.
- A table has a record per row, as a table of its header and that row. The rows share a `table` field.
- JSX elements are replaced by their content, except those kept as HTML tags by `filterElement`, which search dialogs render as components.
- A JSX element is a record when it has no children (see `mdxTypes`), or fits on one line.
- Content inside a record isn't recorded again.
By default, `File`, `TypeTable`, `Callout` and `Card` are kept as HTML tags:
```ts title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkStructureOptions: {
filterElement: (node) => node.name === 'Callout' || node.name === 'Banner',
},
},
});
```
## Plugins [#plugins]
Nodes inserted by plugins aren't recorded, a plugin adds the records of its node with `data.structuredData`:
```ts
node.data = {
...node.data,
structuredData: {
// `heading` defaults to the current heading
contents: [{ heading: undefined, content: 'Generated **content**' }],
},
};
```
To change the Markdown of authored content in records only, edit the `search` namespace with [`replaceSource()`](/docs/headless/mdx/stringification#editing-the-output).
## As a Function [#as-a-function]
```ts
import { structure } from 'fumadocs-core/mdx-plugins';
import remarkMath from 'remark-math';
// with the remark plugins your content needs
const data = structure(content, [remarkMath], options);
```
## Options [#options]
### StructureOptions
| Prop | Type | Description |
| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `types?` | `union` | MDAST node types to be scanned as a content block. If a node's type is listed in this array, it will be converted into a single content block, except tables which become a content block per row, along with the header row. Default: `['heading', 'paragraph', 'blockquote', 'table', 'mdxJsxFlowElement']` |
| `mdxTypes?` | `function` | Whether the MDX element should be treated as a single content block, only effective if `types` has `mdxJsxFlowElement`. Default: return `true` if the element is a leaf node, otherwise `false`. |
| `filterElement?` | `function` | Return `true` to keep a JSX element as an HTML tag, other elements are replaced by their content. Default: keep `File`, `TypeTable`, `Callout` and `Card` elements. |
| `exportAs?` | `union` | export as `structuredData` (if true) or specified variable name. |
# Fumadocs Core (the core library of Fumadocs): Page Slugs & Page Tree
URL: /docs/headless/page-conventions
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/page-conventions.mdx
Customize generated page slugs and page tree.
> This guide only applies for content sources that uses `loader()` API, such as **Fumadocs MDX**.
## Overview [#overview]
Fumadocs generates **page slugs** and **page tree** (sidebar items) from your content directory using [`loader()`](/docs/headless/source-api),
the routing functionality will be handled by your React framework.
You can define folders and pages similar to file-system based routing.
To customize its output further, you may use [Loader Plugins](/docs/headless/source-api/plugins).
## File [#file]
For [MDX](https://mdxjs.com) & Markdown file, you can customize page information from frontmatter.
```mdx
---
title: My Page
description: Best document ever
icon: House
---
## Learn More
```
Fumadocs detects from the following properties to construct page trees.
| name | description |
| ------------- | ------------------------------------- |
| `title` | The title of page |
| `description` | The description of page |
| `icon` | The name of icon, see [Icons](#icons) |
Page information is supplied by the content source such as **Fumadocs MDX**.
On Fumadocs MDX, you can specify a [`schema`](/docs/mdx/collections#schema-1) option to customize frontmatter schema.
### Slugs [#slugs]
The slugs of a page are generated from its file path.
| path (relative to content folder) | slugs |
| --------------------------------- | ----------------- |
| `./dir/page.mdx` | `['dir', 'page']` |
| `./dir/index.mdx` | `['dir']` |
## Folder [#folder]
Organize multiple pages, you can create a [Meta file](#meta) to customize folders.
### Folder Group [#folder-group]
By default, putting a file into folder will change its slugs.
You can wrap the folder name in parentheses to avoid impacting the slugs of child files.
| path (relative to content folder) | slugs |
| --------------------------------- | ---------- |
| `./(group-name)/page.mdx` | `['page']` |
### Root Folder [#root-folder]
Marks the folder as a root folder, only items in the opened root folder will be visible.
```json title="meta.json"
{
"title": "Name of Folder",
"description": "The description of root folder (optional)",
"root": true
}
```
For example, when you are opening root folder `framework`, the other folders (e.g. `headless`) are not shown on the sidebar and other navigation elements.
Fumadocs UI renders root folders as [Layout Tabs](/docs/ui/layouts/docs#layout-tabs), which allows users to switch between them.
### Root Type [#root-type]
`root` also accepts a string, the **type** of root folder:
root folders of the same type under the same parent scope are interchangeable, such as versions of the same docs.
```json tab="v1/meta.json"
{
"title": "1.0.0",
"root": "version"
}
```
```json tab="v2/meta.json"
{
"title": "2.0.0",
"root": "version"
}
```
`root: true` is simply the default type, displayed as tabs.
Switching to another root folder of the same type maps a page to its **structural projection**, the page at the same path relative to the root folder:
| Page | Projection in `v2` |
| --------------------- | --------------------------------------------------- |
| `v1/guide.mdx` | `v2/guide.mdx` |
| `v1/python/guide.mdx` | `v2/python/guide.mdx`, nested root folders are kept |
Fumadocs UI renders a [dropdown](/docs/ui/layouts/docs#tabs-groups) for each root folder on the current page's path to switch between root folders of its type, see [Versioning](/docs/navigation#versioning) for a complete example.
## Meta [#meta]
Customize folders by creating a `meta.json` file in the folder.
```json title="meta.json"
{
"title": "Display Name",
"icon": "MyIcon",
"pages": ["index", "getting-started"],
"defaultOpen": true
}
```
| name | description |
| ------------- | -------------------------------------------- |
| `title` | Display name |
| `icon` | The name of icon, see [Icons](#icons) |
| `defaultOpen` | Open the folder by default |
| `collapsible` | Collapsible folder content (default: `true`) |
| `pages` | Folder items (see below) |
| `pagesIndex` | The index item (see below) |
### Pages [#pages]
Folder items are sorted alphabetically by default, you can add or control the order of items using `pages`.
```json title="meta.json"
{
"pages": ["index", "getting-started"]
}
```
> When specified, items are not included unless they are listed in `pages`.
| Type | Syntax | Description |
| ----------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Path** | `./path/to/page` | a path to page or folder. |
| **Separator** | `---Label---`
`---[Icon]Label---` | a separator between two sections (icon supported). | | **Link** | `[Text](url)`
`[Icon][Text](url)`
`external:[Text](url)` | insert links (icon supported)
add a `external:` prefix to mark links as external. | | **Rest** | `...` | include remaining pages (sorted alphabetically). | | **Reversed Rest** | `z...a` | reversed **Rest** item. | | **Extract** | `...folder` | extract the items from a folder. | | **Except** | `!item` | Exclude an item from `...` or `z...a`. | ```json title="meta.json" { "pages": [ "components", "---My Separator---", "...folder", "...", "!file", "!otherFolder", "[Vercel](https://vercel.com)", "[Triangle][Vercel](https://vercel.com)" ] } ```
The same page URL must not appear more than once in the entire page tree.
Duplicated page items are not allowed for the same reason.
This is intentional, such that Fumadocs can locate the active tree item purely based on current pathname.
### Folder Index [#folder-index]
When folder owns a index item, it becomes clickable and jumps to the index item when clicked.
By default, it is the `index` file under each folder. You can specify the index item of a folder, it accepts **Path** and **Link**.
```json tab="meta.json (Path)"
{
// assume there's a "overview.mdx" file under the folder
"pagesIndex": "overview"
}
```
```json tab="meta.json (Link)"
{
"pagesIndex": "[Example](https://example.com)"
}
```
## Icons [#icons]
Since Fumadocs doesn't include an icon library, you have to convert the icon names to JSX elements in runtime, and render it as a component.
You can add an [`icon` handler](/docs/headless/source-api#icons) to `loader()`.
## i18n Routing [#i18n-routing]
You can define different style for i18n routing.
```ts title="lib/i18n.ts"
import type { I18nConfig } from 'fumadocs-core/i18n';
export const i18n: I18nConfig = {
// default
parser: 'dot',
// or
parser: 'dir',
};
```
Add Markdown/meta files for different languages by attending `.{locale}` to your file name, like:
For the default locale, the locale code is optional.
All content files are grouped by language folders:
# Fumadocs Core (the core library of Fumadocs): Page Tree
URL: /docs/headless/page-tree
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/page-tree.mdx
The structure of page tree.
Page tree is a tree structure that describes all navigation links, with other items like separator and folders.
It will be sent to the client and being referenced in navigation elements including the sidebar and breadcrumb.
Hence, you shouldn't store any sensitive or large data in page tree.
By design, page tree only contains necessary information of all pages and folders.
Unserializable data such as functions can't be passed to page tree.
## Conventions [#conventions]
You can import the type definitions of page tree, useful if you want to hardcode or generate it.
```ts
import type * as PageTree from 'fumadocs-core/page-tree';
const tree: PageTree.Root = {
// props
};
```
Certain nodes contain a `$ref` property, they are internal and not used when hardcoding it.
### Root [#root]
The initial root of page trees.
### PageTreeRoot
| Prop | Type | Description |
| -------------- | ----------- | ------------------------------------------------------------------------- |
| `type?` | `"root"` | |
| `name` | `ReactNode` | |
| `description?` | `ReactNode` | |
| `children` | `array` | |
| `fallback?` | `object` | Another page tree that won't be displayed unless being opened. |
| `$id?` | `string` | ID for the node, unique in all page trees (even across different locales) |
### Page [#page]
A node representing link.
```json
{
"type": "page",
"name": "Quick Start",
"url": "/docs"
}
```
> External urls are also supported
### PageTreeItem
| Prop | Type | Description |
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| `type` | `"page"` | |
| `name` | `ReactNode` | |
| `url` | `string` | |
| `external?` | `union` | Whether the link should be treated as external (e.g. use HTML tag). When unspecified, it depends on the value of `url`. |
| `description?` | `ReactNode` | |
| `icon?` | `ReactNode` | |
| `$id?` | `string` | ID for the node, unique in all page trees (even across different locales) |
### Folder [#folder]
A node containing multiple children nodes.
```json
{
"type": "folder",
"name": "Guide",
"index": {
"type": "page",
...
}
"children": [
...
]
}
```
### PageTreeFolder
| Prop | Type | Description |
| -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `"folder"` | |
| `name` | `ReactNode` | |
| `description?` | `ReactNode` | |
| `root?` | `union` | Mark as a root folder, `true` for the default type. A string value specifies its **root type**: root folders of the same type under the same parent scope are interchangeable (e.g. versions), and pages can map to their structural projection in another root. |
| `defaultOpen?` | `union` | |
| `collapsible?` | `union` | |
| `index?` | `object` | |
| `icon?` | `ReactNode` | |
| `children` | `array` | |
| `$id?` | `string` | ID for the node, unique in all page trees (even across different locales) |
### Separator [#separator]
A label between items.
```json
{
"type": "separator",
"name": "Components"
}
```
### PageTreeSeparator
| Prop | Type | Description |
| ------- | ------------- | ------------------------------------------------------------------------- |
| `type` | `"separator"` | |
| `name?` | `ReactNode` | |
| `icon?` | `ReactNode` | |
| `$id?` | `string` | ID for the node, unique in all page trees (even across different locales) |
## Icons [#icons]
Icon is a `ReactElement`, supported by pages and folders.
# Fumadocs Core (the core library of Fumadocs): Algolia Search
URL: /docs/headless/search/algolia
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/algolia.mdx
Integrate Algolia Search with Fumadocs
If you're using Algolia's free tier, you have to [display their logo on your search
dialog](https://algolia.com/policies/free-services-terms).
## Setup [#setup]
Install dependencies:
```package-install
algoliasearch
```
### Sign up on Algolia [#sign-up-on-algolia]
Sign up and obtain the app id and API keys for your search, store them in `.env.local` (`VITE_` instead of `NEXT_PUBLIC_` outside Next.js):
```dotenv
NEXT_PUBLIC_ALGOLIA_APP_ID="app ID"
NEXT_PUBLIC_ALGOLIA_SEARCH_KEY="search-only API key"
ALGOLIA_WRITE_KEY="write API key"
```
### Sync Search Indexes [#sync-search-indexes]
Pre-render a `static.json` route to export the search indexes on build, and sync them to Algolia with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export const revalidate = false;
export async function GET() {
return Response.json(await toDocuments(source));
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/algolia';
import { algoliasearch } from 'algoliasearch';
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
const client = algoliasearch(
process.env.NEXT_PUBLIC_ALGOLIA_APP_ID!,
process.env.ALGOLIA_WRITE_KEY!,
);
await sync(client, {
indexName: 'document',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export async function loader() {
return Response.json(await toDocuments(source));
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/algolia';
import { algoliasearch } from 'algoliasearch';
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
const client = algoliasearch(
process.env.VITE_ALGOLIA_APP_ID!,
process.env.ALGOLIA_WRITE_KEY!,
);
await sync(client, {
indexName: 'document',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await toDocuments(source)),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/algolia';
import { algoliasearch } from 'algoliasearch';
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
const client = algoliasearch(
process.env.VITE_ALGOLIA_APP_ID!,
process.env.ALGOLIA_WRITE_KEY!,
);
await sync(client, {
indexName: 'document',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export async function GET() {
return Response.json(await toDocuments(source));
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/algolia';
import { algoliasearch } from 'algoliasearch';
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
const client = algoliasearch(
process.env.VITE_ALGOLIA_APP_ID!,
process.env.ALGOLIA_WRITE_KEY!,
);
await sync(client, {
indexName: 'document',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
`sync()` updates the index settings and replaces all records. The `build` script syncs on every build, set the same variables on your deployment platform.
### Search UI [#search-ui]
You can consider different options for implementing the UI:
- Using [Fumadocs UI search dialog](/docs/search/algolia).
- Build your own using the built-in search client hook:
```ts twoslash
import { liteClient } from 'algoliasearch/lite';
import { useAlgoliaSearch } from 'fumadocs-core/search/client';
const algolia = liteClient('id', 'key');
const { search, onSearchChange, isLoading, data } = useAlgoliaSearch({
indexName: 'document',
client: algolia,
});
```
- Use their official clients directly.
## Advanced [#advanced]
### Tag Filter [#tag-filter]
To configure tag filtering, pass a `tag` to `toDocuments()` in the `static.json` route:
```ts
toDocuments(source, { tag: (page) => page.slugs[0] });
```
And update your search client:
- **Fumadocs UI**: Enable [Tag Filter](/docs/search/algolia#tag-filter) on Search UI.
- **Search Client**: You can add the tag filter like:
```ts
import { useAlgoliaSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useAlgoliaSearch({
tag: '',
// ...
});
```
The `tag` field is an attribute for faceting. You can also use the filter `tag:value` on Algolia search clients.
### Under the Hood [#under-the-hood]
The Algolia Integration automatically configures Algolia Search for document search.
It creates a record for **each paragraph** in your document, it is also recommended by Algolia.
Each record contains searchable attributes:
| Attribute | Description |
| --------- | --------------------- |
| `title` | Page Title |
| `section` | Heading ID (nullable) |
| `content` | Paragraph content |
The `section` field only exists in paragraphs under a heading. Headings and
paragraphs are indexed as an individual record, grouped by their page ID.
Notice that it expects the `url` property of a page to be unique, you shouldn't have two pages with the same
url.
# Fumadocs Core (the core library of Fumadocs): FlexSearch
URL: /docs/headless/search/flexsearch
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/flexsearch.mdx
Fast & minimal document search
## Setup [#setup]
```npm
npm install flexsearch
```
```npm
npm install @types/flexsearch -D
```
### From Source [#from-source]
Create the server from source object.
```ts title="app/api/search/route.ts (Next.js)"
import { source } from '@/lib/source';
import { flexsearchFromSource } from 'fumadocs-core/search/flexsearch';
export const { GET } = flexsearchFromSource(source);
```
### From Search Indexes [#from-search-indexes]
Create the server from search indexes, each index needs a `structuredData` field.
Usually, it is provided by your content source (e.g. Fumadocs MDX). You can also extract it from Markdown/MDX document using the [Remark Structure](/docs/headless/mdx/structure) plugin.
```ts title="app/api/search/route.ts (Next.js)"
import { source } from '@/lib/source';
import { flexsearch } from 'fumadocs-core/search/flexsearch';
export const { GET } = flexsearch({
indexes: source.getPages().map((page) => ({
title: page.data.title!,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
})),
});
```
### Searching Documents [#searching-documents]
You can search documents using:
- **Fumadocs UI**: Supported out-of-the-box, see [Search UI](/docs/search/flexsearch) for details.
- **Search Client**:
```ts twoslash
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch();
```
### $Fumadocs
| Prop | Type | Description |
| --------- | -------- | ------------------------------------------------------------------------------ |
| `api?` | `string` | API route for search endpoint, support absolute URLs. Default: `'/api/search'` |
| `tag?` | `union` | Filter results with specific tag(s). |
| `locale?` | `string` | Filter by locale |
| `cache?` | `object` | |
## Configurations [#configurations]
### Tag Filter [#tag-filter]
Support filtering results by tag, it's useful for implementing multi-docs similar to this documentation.
```ts
import { source } from '@/lib/source';
import { flexsearchFromSource } from 'fumadocs-core/search/flexsearch';
const server = flexsearchFromSource(source, {
buildIndex(page) {
return {
title: page.data.title!,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
// use your desired value, like page.slugs[0] [!code ++]
tag: '',
};
},
});
```
and update your search client:
- **Fumadocs UI**: Configure [Tag Filter](/docs/search/flexsearch#tag-filter) on Search UI.
- **Search Client**: pass a tag to `useFetchSearch()`.
```ts
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch({
tag: '', // [!code ++]
});
```
### Static Mode [#static-export]
To support usage with static site, use `staticGET` from search server and make the route static or pre-rendered.
```ts title="app/api/search/route.ts (Next.js)"
import { source } from '@/lib/source';
import { flexsearchFromSource } from 'fumadocs-core/search/flexsearch';
// statically cached [!code highlight:2]
export const revalidate = false;
export const { staticGET: GET } = flexsearchFromSource(source);
```
> `staticGET` is also available on `flexsearch()`.
and update your search clients:
- **Fumadocs UI**: use [static client](/docs/search/flexsearch#static) on Search UI.
- **Search Client**: change your client adapter.
```ts
import { useFlexsearchStatic } from 'fumadocs-core/search/client/flexsearch-static';
const { search, onSearchChange, isLoading, data } = useFlexsearchStatic({
// optional: pass tag & locale
tag,
});
```
### $Fumadocs
| Prop | Type | Description |
| --------- | -------- | ------------------------ |
| `from?` | `string` | Default: ``/api/search`` |
| `locale?` | `string` | |
| `tag?` | `union` | |
Static Search requires clients to download the exported search indexes.
For large docs sites, it can be expensive.
You should use cloud solutions like Orama Cloud or Algolia for these cases.
## Internationalization [#internationalization]
Flexsearch doesn't require configurations to work for other languages, but you can improve the results by specifying Flexsearch options for each locale.
```ts title="app/api/search/route.ts" tab="From Source"
import { source } from '@/lib/source';
import { flexsearchFromSource } from 'fumadocs-core/search/flexsearch';
import { Charset } from 'flexsearch';
const server = flexsearchFromSource(source, {
localeMap: {
// [locale]: Flexsearch options [!code ++]
jp: { encoder: Charset.CJK },
},
});
```
```ts tab="From Search Indexes"
import { source } from '@/lib/source';
import { flexsearchI18n } from 'fumadocs-core/search/flexsearch';
import { i18n } from '@/lib/i18n';
import { Charset } from 'flexsearch';
const server = flexsearchI18n({
i18n, // [!code ++]
localeMap: {
// [locale]: Flexsearch options [!code ++]
jp: { encoder: Charset.CJK },
},
indexes: source.getPages().map((page) => ({
title: page.data.title!,
description: page.data.description,
structuredData: page.data.structuredData,
id: page.url,
url: page.url,
locale: page.locale!,
})),
});
```
# Fumadocs Core (the core library of Fumadocs): Search
URL: /docs/headless/search
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/index.mdx
Configure Search in Fumadocs
# Fumadocs Core (the core library of Fumadocs): Meilisearch
URL: /docs/headless/search/meilisearch
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/meilisearch.mdx
Integrate Meilisearch with Fumadocs
[Meilisearch](https://www.meilisearch.com) is an open-source search engine with typo tolerance and filtering, you can self-host it or use Meilisearch Cloud.
## Setup [#setup]
Install dependencies:
```package-install
meilisearch
```
### API Keys [#api-keys]
Start a Meilisearch instance by [self-hosting](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch) or on [Meilisearch Cloud](https://www.meilisearch.com/cloud), and store its credentials in `.env.local` (`VITE_` instead of `NEXT_PUBLIC_` outside Next.js):
```dotenv
NEXT_PUBLIC_MEILISEARCH_HOST="URL of your instance"
NEXT_PUBLIC_MEILISEARCH_SEARCH_KEY="search API key"
MEILISEARCH_ADMIN_KEY="Default Admin API Key"
```
The search key is exposed to the browser, [create one](https://www.meilisearch.com/docs/learn/security/basic_security) that can only search the `docs` index. Keep the admin key private.
### Sync Documents [#sync-documents]
Pre-render a `static.json` route to export the search documents on build, and sync them to Meilisearch with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/meilisearch';
export const revalidate = false;
export async function GET() {
return Response.json(await toDocuments(source));
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/meilisearch';
import { Meilisearch } from 'meilisearch';
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
const client = new Meilisearch({
host: process.env.NEXT_PUBLIC_MEILISEARCH_HOST!,
apiKey: process.env.MEILISEARCH_ADMIN_KEY!,
});
await sync(client, {
indexName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/meilisearch';
export async function loader() {
return Response.json(await toDocuments(source));
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/meilisearch';
import { Meilisearch } from 'meilisearch';
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
const client = new Meilisearch({
host: process.env.VITE_MEILISEARCH_HOST!,
apiKey: process.env.MEILISEARCH_ADMIN_KEY!,
});
await sync(client, {
indexName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/meilisearch';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await toDocuments(source)),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/meilisearch';
import { Meilisearch } from 'meilisearch';
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
const client = new Meilisearch({
host: process.env.VITE_MEILISEARCH_HOST!,
apiKey: process.env.MEILISEARCH_ADMIN_KEY!,
});
await sync(client, {
indexName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/meilisearch';
export async function GET() {
return Response.json(await toDocuments(source));
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/meilisearch';
import { Meilisearch } from 'meilisearch';
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
const client = new Meilisearch({
host: process.env.VITE_MEILISEARCH_HOST!,
apiKey: process.env.MEILISEARCH_ADMIN_KEY!,
});
await sync(client, {
indexName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
`sync()` configures the index and replaces its documents, the old documents stay searchable until the new ones are indexed. The `build` script syncs on every build, set the same variables on your deployment platform.
### Search UI [#search-ui]
You can consider different options for implementing the UI:
- Using [Fumadocs UI search dialog](/docs/search/meilisearch).
- Build your own using the built-in search client hook:
```ts twoslash
import { Meilisearch } from 'meilisearch';
import { useMeilisearch } from 'fumadocs-core/search/client';
const client = new Meilisearch({
host: 'host url',
apiKey: 'search api key',
});
const { search, onSearchChange, isLoading, data } = useMeilisearch({
client,
indexName: 'docs',
});
```
### $Fumadocs
| Prop | Type | Description |
| ----------- | -------- | ---------------------------------------- |
| `client` | `object` | Meilisearch client with a search API key |
| `indexName` | `string` | |
| `tag?` | `union` | Filter results with specific tag(s). |
| `locale?` | `string` | Filter results by locale. |
- Use their official clients directly.
## Options [#options]
### Tag Filter [#tag-filter]
To configure tag filtering, pass a `tag` to `toDocuments()` in the `static.json` route:
```ts
toDocuments(source, { tag: (page) => page.slugs[0] });
```
And update your search client:
- **Fumadocs UI**: Enable [Tag Filter](/docs/search/meilisearch#tag-filter) on Search UI.
- **Search Client**: pass a tag to `useMeilisearch()`.
```ts
import { useMeilisearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useMeilisearch({
tag: '', // [!code ++]
// ...
});
```
### Internationalization [#internationalization]
Documents include the locale of their pages, pass `locale` to search in a language:
```ts
import { useI18n } from 'fumadocs-ui/contexts/i18n';
import { useMeilisearch } from 'fumadocs-core/search/client';
const { locale } = useI18n();
const { search, onSearchChange, isLoading, data } = useMeilisearch({
locale, // [!code ++]
// ...
});
```
### Index Settings [#index-settings]
`sync()` only sets `searchableAttributes` and `filterableAttributes`, other settings like synonyms and typo tolerance are kept. You can tune them from the Meilisearch dashboard or the `meilisearch` client.
## Under the Hood [#under-the-hood]
Each heading and paragraph is a document, with the page title, URL and breadcrumbs. Only `content` is searchable, the search client groups results by page.
| Attribute | Description |
| --------- | ------------------------------------------ |
| `type` | `page`, `heading` or `text` |
| `content` | Page title, heading or paragraph |
| `heading` | ID of the heading it belongs to (optional) |
| `tag` | Tag(s) to filter results (optional) |
| `locale` | Locale of page (optional) |
# Fumadocs Core (the core library of Fumadocs): Mixedbread
URL: /docs/headless/search/mixedbread
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/mixedbread.mdx
Integrate Mixedbread Search with Fumadocs
[Mixedbread](https://www.mixedbread.com) provides semantic search, users can search with natural language and find content by meaning rather than keywords.
## Setup [#setup]
Install dependencies:
```package-install
@mixedbread/sdk
```
### API Key [#api-key]
Sign up at [Mixedbread](https://platform.mixedbread.com), create an [API key](https://platform.mixedbread.com/platform?next=api-keys) and a [store](https://platform.mixedbread.com/platform?next=stores) for your docs, and store them in `.env.local`:
```dotenv
MXBAI_API_KEY="your API key"
MIXEDBREAD_STORE_ID="your store ID"
```
Searching runs on your server, the API key is never exposed to the browser.
### Sync Documents [#sync-documents]
Pre-render a `static.json` route to export the search documents on build, and sync them to your store with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/mixedbread';
export const revalidate = false;
export async function GET() {
return Response.json(await toDocuments(source));
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/mixedbread';
import Mixedbread from '@mixedbread/sdk';
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
await sync(new Mixedbread(), {
storeIdentifier: process.env.MIXEDBREAD_STORE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/mixedbread';
export async function loader() {
return Response.json(await toDocuments(source));
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/mixedbread';
import Mixedbread from '@mixedbread/sdk';
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
await sync(new Mixedbread(), {
storeIdentifier: process.env.MIXEDBREAD_STORE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/mixedbread';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await toDocuments(source)),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/mixedbread';
import Mixedbread from '@mixedbread/sdk';
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
await sync(new Mixedbread(), {
storeIdentifier: process.env.MIXEDBREAD_STORE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/mixedbread';
export async function GET() {
return Response.json(await toDocuments(source));
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'fumadocs-core/search/mixedbread';
import Mixedbread from '@mixedbread/sdk';
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
await sync(new Mixedbread(), {
storeIdentifier: process.env.MIXEDBREAD_STORE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
`sync()` uploads a file for each page, and skips the pages unchanged since the last sync. Files of removed pages are deleted, use a store dedicated to your docs. The `build` script syncs on every build, set the same variables on your deployment platform.
### Search API [#search-api]
Create a route to search your store:
```ts title="app/api/search/route.ts"
import { createMixedbreadSearchAPI } from 'fumadocs-core/search/mixedbread';
import Mixedbread from '@mixedbread/sdk';
export const { GET } = createMixedbreadSearchAPI({
client: new Mixedbread(), // reads `MXBAI_API_KEY`
storeIdentifier: process.env.MIXEDBREAD_STORE_ID!,
});
```
### Search UI [#search-ui]
You can consider different options for implementing the UI:
- Using [Fumadocs UI search dialog](/docs/search/mixedbread).
- Build your own using the built-in search client hook:
```ts twoslash
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch({
api: '/api/search',
// every search is a request to Mixedbread
delayMs: 300,
});
```
## Options [#options]
### Tag Filter [#tag-filter]
To configure tag filtering, pass a `tag` to `toDocuments()` in the `static.json` route:
```ts
toDocuments(source, { tag: (page) => page.slugs[0] });
```
And update your search client:
- **Fumadocs UI**: Enable [Tag Filter](/docs/search/mixedbread#tag-filter) on Search UI.
- **Search Client**: pass a tag to `useFetchSearch()`.
```ts
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch({
tag: '', // [!code ++]
// ...
});
```
### Internationalization [#internationalization]
Documents include the locale of their pages, pass `locale` to search in a language:
```ts
import { useI18n } from 'fumadocs-ui/contexts/i18n';
import { useFetchSearch } from 'fumadocs-core/search/client';
const { locale } = useI18n();
const { search, onSearchChange, isLoading, data } = useFetchSearch({
locale, // [!code ++]
// ...
});
```
## Under the Hood [#under-the-hood]
Each page is a file keyed by its URL, with the page title, URL, breadcrumbs, tags and locale as metadata. Its chunks are the title, headings and paragraphs of the page, every result is a chunk:
| Chunk Metadata | Description |
| -------------- | ------------------------------------------ |
| `kind` | `page`, `heading` or `text` |
| `heading` | ID of the heading it belongs to (optional) |
| `table` | Table of a table row (optional) |
# Fumadocs Core (the core library of Fumadocs): Orama Cloud
URL: /docs/headless/search/orama-cloud
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/orama-cloud.mdx
Integrate with Orama Cloud
To begin, create an account on Orama Cloud.
## REST API [#rest-api]
REST API integration requires your docs to upload the indexes.
1. Create a new project with **REST API** data source on Orama Cloud dashboard.
Store your credentials in `.env.local`, for example (`VITE_` instead of `NEXT_PUBLIC_` outside Next.js):
```dotenv
NEXT_PUBLIC_ORAMA_DATASOURCE_ID="Rest API data source ID"
NEXT_PUBLIC_ORAMA_PROJECT_ID="project ID"
NEXT_PUBLIC_ORAMA_API_KEY="public API key"
ORAMA_PRIVATE_API_KEY="private API key"
```
2. Pre-render a `static.json` route to export the search indexes on build, and sync them to Orama Cloud with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/orama-cloud';
export const revalidate = false;
export async function GET() {
return Response.json(await toDocuments(source));
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type OramaDocument as DocumentRecord, sync } from 'fumadocs-core/search/orama-cloud';
import { OramaCloud } from '@orama/core';
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
const orama = new OramaCloud({
projectId: process.env.NEXT_PUBLIC_ORAMA_PROJECT_ID!,
apiKey: process.env.ORAMA_PRIVATE_API_KEY!,
});
await sync(orama, {
index: process.env.NEXT_PUBLIC_ORAMA_DATASOURCE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/orama-cloud';
export async function loader() {
return Response.json(await toDocuments(source));
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type OramaDocument as DocumentRecord, sync } from 'fumadocs-core/search/orama-cloud';
import { OramaCloud } from '@orama/core';
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
const orama = new OramaCloud({
projectId: process.env.VITE_ORAMA_PROJECT_ID!,
apiKey: process.env.ORAMA_PRIVATE_API_KEY!,
});
await sync(orama, {
index: process.env.VITE_ORAMA_DATASOURCE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/orama-cloud';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await toDocuments(source)),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type OramaDocument as DocumentRecord, sync } from 'fumadocs-core/search/orama-cloud';
import { OramaCloud } from '@orama/core';
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
const orama = new OramaCloud({
projectId: process.env.VITE_ORAMA_PROJECT_ID!,
apiKey: process.env.ORAMA_PRIVATE_API_KEY!,
});
await sync(orama, {
index: process.env.VITE_ORAMA_DATASOURCE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/orama-cloud';
export async function GET() {
return Response.json(await toDocuments(source));
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type OramaDocument as DocumentRecord, sync } from 'fumadocs-core/search/orama-cloud';
import { OramaCloud } from '@orama/core';
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
const orama = new OramaCloud({
projectId: process.env.VITE_ORAMA_PROJECT_ID!,
apiKey: process.env.ORAMA_PRIVATE_API_KEY!,
});
await sync(orama, {
index: process.env.VITE_ORAMA_DATASOURCE_ID!,
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
The `build` script syncs on every build, set the same variables on your deployment platform.
### Search Client [#search-client]
To search documents on the client side, consider:
- Using [Fumadocs UI search dialog](/docs/search/orama-cloud).
- Custom search UI using the built-in hook of Fumadocs:
```ts
import { useOramaCloudSearch } from 'fumadocs-core/search/client';
import { OramaCloud } from '@orama/core';
const orama = new OramaCloud({
projectId: process.env.NEXT_PUBLIC_ORAMA_PROJECT_ID,
apiKey: process.env.NEXT_PUBLIC_ORAMA_API_KEY,
});
const params = {
// optional search params
};
const { search, onSearchChange, isLoading, data } = useOramaCloudSearch({
client: orama,
params,
});
```
- Use their search client directly.
## Web Crawler [#web-crawler]
1. Create a Crawler data source from dashboard, and configure it correctly with the "Documentation" preset.
2. Copy the credentials from dashboard.
### Search Client [#search-client-1]
Same as REST API integration, but make sure to set `index` to `crawler`.
```ts
import { useOramaCloudSearch } from 'fumadocs-core/search/client';
import { OramaCloud } from '@orama/core';
const orama = new OramaCloud({
projectId: '',
apiKey: '',
});
const params = {
// optional search params
};
const { search, onSearchChange, isLoading, data } = useOramaCloudSearch({
index: 'crawler',
client: orama,
params,
});
```
It's same for Fumadocs UI.
# Fumadocs Core (the core library of Fumadocs): Built-in Search
URL: /docs/headless/search/orama
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/orama.mdx
Built-in document search of Fumadocs
Fumadocs supports document search with [ZBSearch](https://www.zbsearch.dev), It is the default but also the recommended option since it can be self-hosted and totally free.
## Setup [#setup]
Host the server for handling search requests.
### From Source [#from-source]
Create the server from source object.
```ts tab="Next.js" title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
export const { GET } = createFromSource(source);
```
```ts tab="React Router" title="app/routes/search.ts"
import type { Route } from './+types/search';
import { createFromSource } from 'fumadocs-core/search/server';
import { source } from '@/lib/source';
const server = createFromSource(source);
export async function loader({ request }: Route.LoaderArgs) {
return server.GET(request);
}
```
```ts tab="Tanstack Start" title="src/routes/api/search.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
const server = createFromSource(source);
export const Route = createFileRoute('/api/search')({
server: {
handlers: {
GET: async ({ request }) => server.GET(request),
},
},
});
```
```ts tab="Waku" title="src/pages/_api/api/search.ts"
import { createFromSource } from 'fumadocs-core/search/server';
import { source } from '@/lib/source';
export const { GET } = createFromSource(source);
```
```ts tab="Astro" title="src/pages/api/search.ts"
import type { APIRoute } from 'astro';
import { createFromSource } from 'fumadocs-core/search/server';
import { getStructuredData, source } from '@/lib/source';
const server = createFromSource(source, {
buildIndex(page) {
return {
id: page.data._raw.id,
title: page.data.title,
description: page.data.description,
structuredData: getStructuredData(page.data._raw),
url: page.url,
};
},
});
export const GET: APIRoute = () => {
return server.staticGET();
};
```
### From Search Indexes [#from-search-indexes]
Create the server from search indexes, each index needs a `structuredData` field.
Usually, it is provided by your content source (e.g. Fumadocs MDX). You can also extract it from Markdown/MDX document using the [Remark Structure](/docs/headless/mdx/structure) plugin.
```ts tab="Next.js" title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';
export const { GET } = createSearchAPI('advanced', {
indexes: source.getPages().map((page) => ({
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
})),
});
```
```ts tab="React Router" title="app/routes/search.ts"
import type { Route } from './+types/search';
import { createSearchAPI } from 'fumadocs-core/search/server';
import { source } from '@/lib/source';
const server = createSearchAPI('advanced', {
indexes: source.getPages().map((page) => ({
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
})),
});
export async function loader({ request }: Route.LoaderArgs) {
return server.GET(request);
}
```
```ts tab="Tanstack Start" title="src/routes/api/search.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';
const server = createSearchAPI('advanced', {
indexes: source.getPages().map((page) => ({
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
})),
});
export const Route = createFileRoute('/api/search')({
server: {
handlers: {
GET: async ({ request }) => server.GET(request),
},
},
});
```
```ts tab="Waku" title="src/pages/_api/api/search.ts"
import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';
export const { GET } = createSearchAPI('advanced', {
indexes: source.getPages().map((page) => ({
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
})),
});
```
```ts tab="Astro" title="src/pages/api/search.ts"
import type { APIRoute } from 'astro';
import { createSearchAPI } from 'fumadocs-core/search/server';
import { getStructuredData, source } from '@/lib/source';
const server = createSearchAPI('advanced', {
indexes: source.getPages().map((page) => ({
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: getStructuredData(page.data._raw),
})),
});
export const GET: APIRoute = ({ request }) => server.GET(request);
```
### Searching Documents [#searching-documents]
You can search documents using:
- **Fumadocs UI**: Supported out-of-the-box, see [Search UI](/docs/search/orama) for details.
- **Search Client**:
```ts twoslash
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch();
```
### $Fumadocs
| Prop | Type | Description |
| --------- | -------- | ------------------------------------------------------------------------------ |
| `api?` | `string` | API route for search endpoint, support absolute URLs. Default: `'/api/search'` |
| `tag?` | `union` | Filter results with specific tag(s). |
| `locale?` | `string` | Filter by locale |
| `cache?` | `object` | |
## Configurations [#configurations]
### Tag Filter [#tag-filter]
Support filtering results by tag, it's useful for implementing multi-docs similar to this documentation.
```ts
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
const server = createFromSource(source, {
buildIndex(page) {
return {
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
// use your desired value, like page.slugs[0] [!code ++]
tag: '',
};
},
});
```
and update your search client:
- **Fumadocs UI**: Configure [Tag Filter](/docs/search/orama#tag-filter) on Search UI.
- **Search Client**: pass a tag to `useFetchSearch()`.
```ts
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch({
tag: '', // [!code ++]
});
```
### Static Mode [#static-export]
To support usage with static site, use `staticGET` from search server and make the route static or pre-rendered.
```ts tab="Next.js" title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
// statically cached [!code highlight:2]
export const revalidate = false;
export const { staticGET: GET } = createFromSource(source);
```
```ts tab="React Router" title="app/routes/search.ts"
// make sure this route is pre-rendered in `react-router.config.ts`.
export async function loader() {
// [!code highlight]
return server.staticGET();
}
```
```ts tab="Tanstack Start" title="src/routes/api/search.ts"
import { createFileRoute } from '@tanstack/react-router';
export const Route = createFileRoute('/api/search')({
server: {
handlers: {
// [!code highlight]
GET: async () => server.staticGET(),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
// [!code ++] pre-render the index file
pages: [{ path: '/api/search' }],
}),
],
});
```
```ts tab="Waku" title="src/pages/_api/api/search.ts"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
// [!code highlight]
export const { staticGET: GET } = createFromSource(source);
// statically cached [!code highlight:3]
export const getConfig = async () => ({
render: 'static',
});
```
```ts tab="Astro" title="src/pages/api/search.ts"
import type { APIRoute } from 'astro';
// [!code highlight]
export const GET: APIRoute = () => server.staticGET();
```
> `staticGET` is also available on `createSearchAPI`.
and update your search clients:
- **Fumadocs UI**: use [static client](/docs/search/orama#static) on Search UI.
- **Search Client**: use `useStaticSearch()` instead of `useFetchSearch()`.
```ts
import { useStaticSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useStaticSearch();
```
### $Fumadocs
| Prop | Type | Description |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
| `from?` | `string` | Where to download exported search indexes (URL) Default: `'/api/search'` |
| `initDB?` | `function` | Customize how the search database is initialized (advanced). For legacy per-locale exports, it is called once per locale. |
| `initOrama?` | `function` | **Deprecated.** |
| `tag?` | `union` | Filter results with specific tag(s). |
| `locale?` | `string` | Filter by locale (for i18n) |
| `search?` | `union` | extra options for search |
Static Search requires clients to download the exported search indexes.
For large docs sites, it can be expensive.
You should use cloud solutions like Orama Cloud or Algolia for these cases.
## Internationalization [#internationalization]
Search works with every language out of the box - the default `multilingual` mode uses Unicode word segmentation, so all locales (including Chinese and Japanese) share a single search database with zero config.
```ts title="app/api/search/route.ts" tab="From Source"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
// no extra configuration needed for i18n
const server = createFromSource(source);
```
```ts tab="From Search Indexes"
import { source } from '@/lib/source';
import { createI18nSearchAPI } from 'fumadocs-core/search/server';
import { i18n } from '@/lib/i18n';
const server = createI18nSearchAPI('advanced', {
i18n, // [!code ++]
indexes: source.getLanguages().flatMap(({ language, pages }) =>
pages.map((page) => ({
title: page.data.title,
description: page.data.description,
structuredData: page.data.structuredData,
id: page.url,
url: page.url,
locale: language, // [!code ++]
})),
),
});
```
and update your search clients:
- **Fumadocs UI**: No changes needed, Fumadocs UI handles this when you have i18n configured correctly.
- **Search Client**:
Add `locale` to the search client, this will only allow pages with specified locale to be searchable by the user.
```ts
import { useFetchSearch } from 'fumadocs-core/search/client';
const { search, onSearchChange, isLoading, data } = useFetchSearch({
locale: 'cn',
});
```
This also applies to **Static Mode**, pass `locale` to `useStaticSearch()` instead.
The `multilingual` mode doesn't apply language-specific stemming or stop-words.
Without stemming, a plural query like `recordings` won't match a page containing `recording`.
To attach a stemmer while keeping multilingual segmentation and a single database, pass a `tokenizer`:
```ts
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
import { stemmer } from '@zbsearch/stemmers/english';
const server = createFromSource(source, {
tokenizer: { language: 'multilingual', stemming: true, stemmer }, // [!code ++]
});
```
Alternatively, use a language on the [supported languages](https://www.zbsearch.dev/docs/zbsearch/supported-languages) list per locale with `localeMap`:
```ts
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
const server = createFromSource(source, {
localeMap: {
// [locale]: search options [!code ++:2]
ru: { language: 'russian' },
en: { language: 'english' },
},
});
```
Note that a separate search database is created for each locale when `localeMap` is enabled.
A custom `tokenizer` must also be given to the client, since it needs to tokenize the query the same way.
Pass it via `initDB` on `useStaticSearch()`.
## Headless [#headless]
You can host the search server on other backend such as Express and Elysia.
```ts
import { initAdvancedSearch } from 'fumadocs-core/search/server';
const server = initAdvancedSearch({
// you still have to pass indexes
});
server.search('query', {
// you can specify `locale` and `tag` here
});
```
# Fumadocs Core (the core library of Fumadocs): Trieve Search
URL: /docs/headless/search/trieve
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/trieve.mdx
Integrate Trieve Search with Fumadocs
> This is a community maintained integration.
## Introduction [#introduction]
The Trieve Integration automatically configures Trieve Search for site search.
By default, it creates a chunk for **each paragraph** in your document, it is
officially recommended by Trieve.
## Setup [#setup]
### Install Dependencies [#install-dependencies]
```package-install
trieve-ts-sdk trieve-fumadocs-adapter
```
### Sign up on Trieve [#sign-up-on-trieve]
Sign up and create a dataset. Then obtain 2 API keys where one has only read access and the other has admin access to create and delete chunks.
Store the dataset ID and admin key in `.env.local` for syncing:
```dotenv
TRIEVE_DATASET_ID="dataset ID"
TRIEVE_ADMIN_API_KEY="admin API key"
```
One API Key should have only read access for the public facing search and the other should have
admin access to create and delete chunks.
### Sync Dataset [#sync-dataset]
Trieve takes the records of the [Algolia integration](/docs/headless/search/algolia). Export them with a pre-rendered `static.json` route, and sync them to Trieve with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export const revalidate = false;
export async function GET() {
return Response.json(await toDocuments(source));
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { sync, type TrieveDocument as DocumentRecord } from 'trieve-fumadocs-adapter/search/sync';
import { TrieveSDK } from 'trieve-ts-sdk';
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
const client = new TrieveSDK({
apiKey: process.env.TRIEVE_ADMIN_API_KEY!,
datasetId: process.env.TRIEVE_DATASET_ID!,
});
await sync(client, records);
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export async function loader() {
return Response.json(await toDocuments(source));
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { sync, type TrieveDocument as DocumentRecord } from 'trieve-fumadocs-adapter/search/sync';
import { TrieveSDK } from 'trieve-ts-sdk';
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
const client = new TrieveSDK({
apiKey: process.env.TRIEVE_ADMIN_API_KEY!,
datasetId: process.env.TRIEVE_DATASET_ID!,
});
await sync(client, records);
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await toDocuments(source)),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { sync, type TrieveDocument as DocumentRecord } from 'trieve-fumadocs-adapter/search/sync';
import { TrieveSDK } from 'trieve-ts-sdk';
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
const client = new TrieveSDK({
apiKey: process.env.TRIEVE_ADMIN_API_KEY!,
datasetId: process.env.TRIEVE_DATASET_ID!,
});
await sync(client, records);
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
import { toDocuments } from 'fumadocs-core/search/algolia';
export async function GET() {
return Response.json(await toDocuments(source));
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { sync, type TrieveDocument as DocumentRecord } from 'trieve-fumadocs-adapter/search/sync';
import { TrieveSDK } from 'trieve-ts-sdk';
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
const client = new TrieveSDK({
apiKey: process.env.TRIEVE_ADMIN_API_KEY!,
datasetId: process.env.TRIEVE_DATASET_ID!,
});
await sync(client, records);
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
The `build` script syncs on every build, set the same variables on your deployment platform.
### Search UI [#search-ui]
You can use their `SearchDialog` component:
```tsx title="components/search.tsx"
'use client';
import type { SharedProps } from 'fumadocs-ui/components/dialog/search';
import SearchDialog from 'trieve-fumadocs-adapter/components/dialog/search';
import { TrieveSDK } from 'trieve-ts-sdk';
const trieveClient = new TrieveSDK({
apiKey: 'readOnlyApiKey',
datasetId: 'datasetId',
});
export default function CustomSearchDialog(props: SharedProps) {
return ');
```
# Fumadocs Core (the core library of Fumadocs): Typesense Search
URL: /docs/headless/search/typesense
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/search/typesense.mdx
Integrate Typesense Search with Fumadocs
> This is a community-maintained integration.
## Setup [#setup]
### Install Dependencies [#install-dependencies]
```package-install
typesense typesense-fumadocs-adapter
```
### Start Typesense Server [#start-typesense-server]
You can either self-host the Typesense server or use their cloud service. Follow their [getting started guide](https://typesense.org/docs/guide/install-typesense.html) to set up your server, and store its credentials in `.env.local` (`VITE_` instead of `NEXT_PUBLIC_` outside Next.js):
```dotenv
NEXT_PUBLIC_TYPESENSE_URL="server URL"
NEXT_PUBLIC_TYPESENSE_SEARCH_KEY="search-only API key"
TYPESENSE_API_KEY="API key with write access"
```
### Sync Dataset [#sync-dataset]
Export the search indexes with a pre-rendered `static.json` route, and sync them to Typesense with a script after each build:
```ts tab="Next.js" title="app/static.json/route.ts"
import { source } from '@/lib/source';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
async function getDocuments() {
const documents: DocumentRecord[] = [];
for (const page of source.getPages()) {
documents.push({
_id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
locale: page.locale,
});
}
return documents;
}
export const revalidate = false;
export async function GET() {
return Response.json(await getDocuments());
}
```
```ts tab="Next.js" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'typesense-fumadocs-adapter';
import { Client } from 'typesense';
const records = JSON.parse(await fs.readFile('.next/server/app/static.json.body', 'utf-8')) as DocumentRecord[];
const client = new Client({
nodes: [{ url: process.env.NEXT_PUBLIC_TYPESENSE_URL! }],
apiKey: process.env.TYPESENSE_API_KEY!,
connectionTimeoutSeconds: 60 * 15,
});
await sync(client, {
typesenseCollectionName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Next.js" title="package.json"
{
"scripts": {
"build": "next build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="React Router" title="app/routes/static.json.ts"
import { source } from '@/lib/source';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
async function getDocuments() {
const documents: DocumentRecord[] = [];
for (const page of source.getPages()) {
documents.push({
_id: page.url,
structured: await page.data.structuredData(),
url: page.url,
title: page.data.title,
description: page.data.description,
locale: page.locale,
});
}
return documents;
}
export async function loader() {
return Response.json(await getDocuments());
}
```
```ts tab="React Router" title="app/routes.ts"
import { index, route, type RouteConfig } from '@react-router/dev/routes';
export default [
index('routes/home.tsx'),
route('static.json', 'routes/static.json.ts'), // [!code ++:1]
] satisfies RouteConfig;
```
```ts tab="React Router" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'typesense-fumadocs-adapter';
import { Client } from 'typesense';
const records = JSON.parse(await fs.readFile('build/client/static.json', 'utf-8')) as DocumentRecord[];
const client = new Client({
nodes: [{ url: process.env.VITE_TYPESENSE_URL! }],
apiKey: process.env.TYPESENSE_API_KEY!,
connectionTimeoutSeconds: 60 * 15,
});
await sync(client, {
typesenseCollectionName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="React Router" title="package.json"
{
"scripts": {
"build": "react-router build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Tanstack Start" title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
async function getDocuments() {
const documents: DocumentRecord[] = [];
for (const page of source.getPages()) {
documents.push({
_id: page.url,
structured: await page.data.structuredData(),
url: page.url,
title: page.data.title,
description: page.data.description,
locale: page.locale,
});
}
return documents;
}
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await getDocuments()),
},
},
});
```
```ts tab="Tanstack Start" title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
tanstackStart({
prerender: {
enabled: true,
},
pages: [ // [!code ++:3]
{ path: '/static.json' }
],
}),
nitro({
preset: 'vercel',
}),
],
});
```
```ts tab="Tanstack Start" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'typesense-fumadocs-adapter';
import { Client } from 'typesense';
const records = JSON.parse(await fs.readFile('.vercel/output/static/static.json', 'utf-8')) as DocumentRecord[];
const client = new Client({
nodes: [{ url: process.env.VITE_TYPESENSE_URL! }],
apiKey: process.env.TYPESENSE_API_KEY!,
connectionTimeoutSeconds: 60 * 15,
});
await sync(client, {
typesenseCollectionName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Tanstack Start" title="package.json"
{
"scripts": {
"build": "vite build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
```ts tab="Waku" title="src/pages/_api/static.json.ts"
import { source } from '@/lib/source';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
async function getDocuments() {
const documents: DocumentRecord[] = [];
for (const page of source.getPages()) {
documents.push({
_id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
locale: page.locale,
});
}
return documents;
}
export async function GET() {
return Response.json(await getDocuments());
}
export async function getConfig() {
return {
render: 'static' as const,
} as const;
}
```
```ts tab="Waku" title="scripts/sync-content.ts"
import * as fs from 'node:fs/promises';
import { type DocumentRecord, sync } from 'typesense-fumadocs-adapter';
import { Client } from 'typesense';
const records = JSON.parse(await fs.readFile('dist/public/static.json', 'utf-8')) as DocumentRecord[];
const client = new Client({
nodes: [{ url: process.env.VITE_TYPESENSE_URL! }],
apiKey: process.env.TYPESENSE_API_KEY!,
connectionTimeoutSeconds: 60 * 15,
});
await sync(client, {
typesenseCollectionName: 'docs',
documents: records,
});
console.log(`search updated: ${records.length} records`);
```
```json tab="Waku" title="package.json"
{
"scripts": {
"build": "waku build && node --env-file-if-exists=.env.local scripts/sync-content.ts"
}
}
```
The `build` script syncs on every build, set the same variables on your deployment platform.
### Search UI [#search-ui]
To implement the search UI, you can either:
- Use [Fumadocs UI search dialog](/docs/search/typesense).
- Build your own search UI with the Typesense search client hook.
```ts
import { Client } from 'typesense';
import { useTypesenseSearch } from 'typesense-fumadocs-adapter/client';
const client = new Client({
nodes: [{ url: 'YOUR_TYPESENSE_SERVER_URL' }],
apiKey: 'YOUR_TYPESENSE_SEARCH_ONLY_API_KEY',
});
const { search, setSearch, query } = useTypesenseSearch({
typesenseCollectionName: 'docs',
client,
});
```
## Options [#options]
### Tag Filter [#tag-filter]
To configure tag filtering, add a `tag` value to the documents in the `static.json` route:
```ts
documents.push({
// other fields...
// [!code ++]
tag: '',
});
```
And update your search client:
- **Fumadocs UI**: Enable [Tag Filter](/docs/search/typesense#tag-filter) on Search UI.
- **Search Client**: You can add the tag filter like:
```ts
import { useTypesenseSearch } from 'typesense-fumadocs-adapter/client';
const { search, setSearch, query } = useTypesenseSearch({
tag: '',
// ...
});
```
### Internationalization (i18n) [#internationalization-i18n]
Documents include the `locale` of their pages, pass `locale` to the search client:
```ts
import { useI18n } from 'fumadocs-ui/contexts/i18n';
import { useTypesenseSearch } from 'typesense-fumadocs-adapter/client';
const { locale } = useI18n();
const { search, setSearch, query } = useTypesenseSearch({
// [!code ++]
locale,
// other fields...
});
```
Under the hood, Typesense will create separate collections for each locale. The collection name is appended with the `_{locale}` suffix (e.g., `docs_en`, `docs_fr`).
# Fumadocs Core (the core library of Fumadocs): Loader API
URL: /docs/headless/source-api
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/source-api/index.mdx
Turn content sources into a unified interface
## What it does? [#what-it-does]
`loader()` provides an interface for Fumadocs to integrate with different content sources.
- Generate [page slugs and page tree](/docs/headless/page-conventions).
- Assign URL to each page.
- Output useful utilities to interact with content.
- `loader()` is a server-side API, not a build-time magic or browser compatible API.
- It uses in-memory storage, the files are passed from your content sources.
## Usage [#usage]
You can use it with content sources like Fumadocs MDX, see [`source`](/docs/headless/source-api/source) for details.
```ts
import { loader } from 'fumadocs-core/source';
import { docs } from 'collections/server';
export const source = loader({
source: docs.toFumadocsSource(),
baseUrl: '/docs',
});
```
### URL [#url]
You can override the base URL, or specify a function to generate URL for each page.
```ts
import { loader } from 'fumadocs-core/source';
loader({
baseUrl: '/docs',
// or you can customize it with function
url(slugs, locale) {
if (locale) return '/' + [locale, 'docs', ...slugs].join('/');
return '/' + ['docs', ...slugs].join('/');
},
});
```
### Slugs [#slugs]
Define a custom function to generate slugs from page files.
```ts
import { loader } from 'fumadocs-core/source';
loader({
slugs(file, next) {
console.log(file.path, file.data);
// you can build on the default slugs with `next()`
if (file.path.startsWith('blog/')) return ['blog', ...next()];
// or return `undefined` to fallback to default value
return ['my', 'slug'];
},
});
```
### Icons [#icons]
Load the [icon](/docs/headless/page-conventions#icons) property specified by page and meta files.
```ts
import { loader } from 'fumadocs-core/source';
import { icons } from 'lucide-react';
import { createElement } from 'react';
loader({
icon(icon) {
if (!icon) {
// You may set a default icon
return;
}
if (icon in icons) return createElement(icons[icon as keyof typeof icons]);
},
});
```
### I18n [#i18n]
Pass the `i18n` config to loader.
```ts title="lib/source.ts"
import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';
export const source = loader({
i18n, // [!code highlight]
});
```
With i18n enabled, loader will generate a page tree for every locale.
If translations are missing for a page, it fallbacks to [`fallbackLanguage`](/docs/headless/internationalization/config#fallback-language).
## Output [#output]
It outputs a content loader instance.
### Get Page [#get-page]
Get page with slugs.
```ts
import { source } from '@/lib/source';
source.getPage(['slug', 'of', 'page']);
// with i18n
source.getPage(['slug', 'of', 'page'], 'locale');
```
### Get Pages [#get-pages]
Get a list of page available for locale.
```ts
import { source } from '@/lib/source';
// from any locale
source.getPages();
// for a specific locale
source.getPages('locale');
```
### Page Tree [#page-tree]
```ts
import { source } from '@/lib/source';
// without i18n
source.getPageTree();
// with i18n
source.getPageTree('locale');
```
### Get from Node [#get-from-node]
The page tree nodes contain references to their original file path.
You can find their original page or meta file from the tree nodes.
```ts
import { source } from '@/lib/source';
source.getNodePage(pageNode);
source.getNodeMeta(folderNode);
```
### Params [#params]
A function to generate output for Next.js `generateStaticParams`.
The generated parameter names will be `slug: string[]` and `lang: string` (i18n only).
```ts title="app/[[...slug]]/page.tsx"
import { source } from '@/lib/source';
export function generateStaticParams() {
return source.generateParams();
}
```
### Language Entries [#language-entries]
Get available languages and its pages.
```ts
import { source } from '@/lib/source';
// language -> pages
const entries = source.getLanguages();
```
## Client API [#client-api]
Loader API is best when used in RSC environments, which allows passing JSX nodes across the server-client boundary.
For non-RSC environments, it provides a tiny serialization layer.
```ts tab="Server"
import { source } from '@/lib/source';
// where you pass loader data
async function loader() {
const pageTree = source.getPageTree();
return {
pageTree: await source.serializePageTree(pageTree),
};
}
```
```tsx tab="Client"
import { useFumadocsLoader } from 'fumadocs-core/source/client';
function MyComponent() {
// `useLoaderData()` receives loader data (provided by your React framework)
const { pageTree, ...data } = useFumadocsLoader(useLoaderData());
// now render it (e.g. via Fumadocs UI)
return ... ;
}
```
## Dynamic Loader [#dynamic-loader]
`dynamicLoader()` provides extra revalidation functionality to content sources, you should use it with a [dynamic source](/docs/headless/source-api/source#dynamic-source).
```ts
import { dynamicLoader } from 'fumadocs-core/source';
import { createMySource } from './my-source';
const source = dynamicLoader(createMySource(), {
baseUrl: '/docs',
});
export async function getSource() {
return source.get();
}
```
When you call `await source.get()`, it returns a normal content loader object:
```ts
const docs = await getSource();
const page = docs.getPage(['...']);
```
### Revalidation [#revalidation]
Dynamic sources are cached by the loader.
If your source changes over time, call `invalidate()` to clear the cache, or `revalidate()` to update the cache:
```ts
source.invalidate();
await source.revalidate();
```
For [multi-source](/docs/headless/source-api/source#multiple-sources) setups, you can invalidate/revalidate a specific source:
```ts
source.invalidate('docs');
await source.revalidate('docs');
```
# Fumadocs Core (the core library of Fumadocs): Loader Plugins
URL: /docs/headless/source-api/plugins
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/source-api/plugins.mdx
Extend Loader API
## Overview [#overview]
Loader plugins can extend `loader()` to customize its output.
A list of built-in plugins:
- **Lucide Icons**: use icons from [Lucide React](https://lucide.dev) (require `lucide-react` to be installed).
```ts
import { loader } from 'fumadocs-core/source';
import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
export const source = loader({
// ...
plugins: [lucideIconsPlugin()],
});
```
## Creating Plugins [#creating-plugins]
Each plugin is an object:
```ts tab="Strictly Typed"
import { loader } from 'fumadocs-core/source';
export const source = loader({
plugins: ({ typedPlugin }) => [
typedPlugin({
// plugin config
}),
],
});
```
```ts tab="Simple"
import { loader, type LoaderPlugin } from 'fumadocs-core/source';
export const source = loader({
plugins: [myPlugin()],
});
function myPlugin(): LoaderPlugin {
return {
// plugin config
};
}
```
`typedPlugin` enforces a more accurate type for plugin, including custom properties from your content source.
But to make the plugin reusable (across different loaders), use the `LoaderPlugin` type instead.
### Storage [#storage]
During the process, your input source files will be parsed and form a virtual storage in memory.
To perform virtual file-system operations before processing, you can hook `transformStorage`.
```ts
import { loader } from 'fumadocs-core/source';
export const source = loader({
plugins: ({ typedPlugin }) => [
typedPlugin({
transformStorage({ storage }) {
storage.read('my/path');
},
}),
],
});
```
### Page Tree [#page-tree]
The page tree is generated from your file system, some unnecessary information (e.g. unused frontmatter properties) will be filtered.
You can customize it using the `transformPageTree`, such as attaching custom properties to nodes, or customising the display name of pages.
```tsx
import { loader } from 'fumadocs-core/source';
export const source = loader({
plugins: ({ typedPlugin }) => [
typedPlugin({
transformPageTree: {
file(node, file) {
// access the original (unfiltered) file data
if (file) console.log(this.storage.read(file));
// modify nodes
node.name = <>Some JSX Nodes here;
return node;
},
},
}),
],
});
```
# Fumadocs Core (the core library of Fumadocs): Source
URL: /docs/headless/source-api/source
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/source-api/source.mdx
Setup sources for Loader API
## Overview [#overview]
Content loader accepts different content sources based on a `source` interface.
### Multiple Sources [#multiple-sources]
Pass a record of source objects instead
```ts
import { loader } from 'fumadocs-core/source';
import { blog, docs } from 'collections/server';
import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
export const source = loader(
{
docs: docs.toFumadocsSource(),
openapi: blog.toFumadocsSource(),
},
{
baseUrl: '/docs',
},
);
```
To access properties exclusive to each source:
```ts
const page = source.getPage(['...']);
if (page.type === 'docs') {
console.log(page.data);
} else {
console.log(page.data);
}
```
### Static Source [#static-source]
To plug your own content source, create a `StaticSource` object.
Since Loader API doesn't rely on file system, file paths only allow virtual paths like `file.mdx` and `content/file.mdx`, `./file.mdx` and `D://content/file.mdx` are not allowed.
```ts twoslash
import type { StaticSource } from 'fumadocs-core/source';
export function createMySource(): StaticSource<{
metaData: { title: string; pages: string[] }; // Your custom type
pageData: { title: string; description?: string }; // Your custom type
}> {
return {
files: [
{
type: 'page',
path: 'folder/index.mdx',
data: {
title: 'Hello World',
// ...
},
},
{
type: 'meta',
path: 'meta.json',
data: {
title: 'Docs',
pages: ['folder'],
// ...
},
},
],
};
}
```
### Dynamic Source [#dynamic-source]
For content sources with revalidation, return a `DynamicSource` instead:
```ts
import type { DynamicSource } from 'fumadocs-core/source';
export function createMySource(): DynamicSource<{
metaData: { title: string; pages: string[] };
pageData: { title: string; description?: string };
}> {
return {
async files() {
return [
{
type: 'page',
path: 'folder/index.mdx',
data: {
title: 'Hello World',
},
},
{
type: 'meta',
path: 'meta.json',
data: {
title: 'Docs',
pages: ['folder'],
},
},
];
},
configure(loader) {
// you can revalidate the loader from source, e.g.
onMyEvent(() => {
void loader.revalidate();
});
},
};
}
```
Dynamic sources can only be consumed by [`dynamicLoader()`](/docs/headless/source-api#dynamic-loader).
# Fumadocs Core (the core library of Fumadocs): Get TOC
URL: /docs/headless/utils/get-toc
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/get-toc.mdx
Parse Table of contents from markdown/mdx content
Parse Table of contents from markdown/mdx content.
> [You can use the remark plugin directly](/docs/headless/mdx/headings)
## Usage [#usage]
Note: If you're using a CMS, you should use the API provided by the CMS instead.
```ts
import { getTableOfContents } from 'fumadocs-core/content/toc';
const toc = getTableOfContents('## markdown content');
```
### Output [#output]
An array of [`TOCItemType`](/docs/headless/mdx/headings#output) is returned.
# Fumadocs Core (the core library of Fumadocs): Last Modified Time
URL: /docs/headless/utils/git-last-edit
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/git-last-edit.mdx
Get the last edit time of a file in Github repository
## Usage [#usage]
Pass your repository name, and the path to file.
```ts
import { getGithubLastEdit } from 'fumadocs-core/content/github';
const time = await getGithubLastEdit({
owner: 'fuma-nama',
repo: 'fumadocs',
// example: "content/docs/index.mdx"
path: `content/docs/${page.path}`,
});
```
### Github Token [#github-token]
Notice that you may easily reach the rate limit in development mode. Hence, you
should pass a Github token for a higher rate limit.
Learn more about
[Authenticating to the REST API](https://docs.github.com/en/rest/overview/authenticating-to-the-rest-api).
```ts
import { getGithubLastEdit } from 'fumadocs-core/content/github'
const time = await getGithubLastEdit({
...,
token: `Bearer ${process.env.GIT_TOKEN}`
})
```
Also, you can skip this in development mode if you don't need that
functionality.
```ts
process.env.NODE_ENV === 'development'? null : getGithubLastEdit(...)
```
### Custom GitHub Base URL [#custom-github-base-url]
If you need to access GitHub a instance at a url other than `https://api.github.com`, you can override the base URL:
```ts
import { getGithubLastEdit } from 'fumadocs-core/content/github';
const time = await getGithubLastEdit({
owner: 'your-org',
repo: 'your-repo',
path: `content/docs/${page.path}`,
baseUrl: 'https://api.octocorp.ghe.com', // Your custom GitHub API URL
});
```
The `baseUrl` parameter defaults to `'https://api.github.com'` if not specified.
# Fumadocs Core (the core library of Fumadocs): Utilities
URL: /docs/headless/utils
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/index.mdx
Utilities to provide extra functionality to your docs
# Fumadocs Core (the core library of Fumadocs): Markdown Rendering
URL: /docs/headless/utils/markdown
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/markdown.mdx
Render React elements into Markdown.
## Overview [#overview]
`fumadocs-core/server` renders React Server Components, into a Markdown document:
```tsx tab="Input"
import { renderToMarkdown } from 'fumadocs-core/server';
const text = await renderToMarkdown(
,
);
```
```md tab="Output"
## Hello World
Some **rich** content.
```
It powers the component exported by [Remark LLMs](/docs/headless/mdx/remark-llms#output) with `output: "function"`, and works on any server-rendered content you want to serve as Markdown.
> `renderToMarkdown()` is server-only.
## `asMarkdown` [#asmarkdown]
Components define their own Markdown form. Calling `asMarkdown()` during render is the opt-in: it returns `true` when the component is being rendered into Markdown, and the HTML elements it returns are converted.
```tsx
import { asMarkdown, md } from 'fumadocs-core/server';
function Callout({ title, children }) {
if (asMarkdown()) return md.linePrefix('> ')`**${title}**\n${children}`;
return ...
```
This includes client components, which don't execute on the server.
## `md` [#md]
Tagged template for Markdown output, interpolated values can be strings, React nodes, promises, or arrays of them. Use it to stringify `children` before manipulating them.
Two variants return the content as a block:
- `md.linePrefix(prefix)`: prefix every line, e.g. `'> '` for quote blocks.
- `md.indent(size)`: indent every line.
## `renderRoute` [#renderroute]
Render a page element into Markdown, or `undefined` when its component doesn't call `asMarkdown()`.
```tsx
import { renderRoute } from 'fumadocs-core/server';
const text = await renderRoute(
The [MCP Server](/docs/integrations/llms#mcp-server) guide sets up a route with these tools for
you.
## Usage [#usage]
```package-install
fumadocs-core @modelcontextprotocol/server zod
```
Register the tools with your source, its [`docsLlms`](/docs/integrations/llms#docsllms) renderer, and a search server:
```ts title="lib/mcp.ts"
import { McpServer } from '@modelcontextprotocol/server';
import { registerSearchTool, registerSourceTools } from 'fumadocs-core/mcp';
import { createFromSource } from 'fumadocs-core/search/server';
import { source, docsLlms } from '@/lib/source';
export const mcp = new McpServer({ name: 'docs', version: '1.0.0' });
// `list_pages` & `get_page`
registerSourceTools(mcp, source, docsLlms);
// `search`
registerSearchTool(mcp, createFromSource(source));
```
For runtime content sources, pass the getter of your source:
```ts
registerSourceTools(mcp, getSource, docsLlms);
```
Then connect the server to a transport, like the streamable HTTP transport.
## Tools [#tools]
| Tool | Input | Output |
| ------------ | ------------------ | --------------------------------------------------- |
| `list_pages` | None | `llms.index()`, the index of pages |
| `get_page` | `url` of a page | `llms.page(page)`, or an error when no page matches |
| `search` | `query`, `locale?` | the search results, as JSON |
# Fumadocs Core (the core library of Fumadocs): Negotiation
URL: /docs/headless/utils/negotiation
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/negotiation.mdx
Content negotiation utilities.
## Overview [#overview]
For React.js frameworks supporting middlewares, you can use the Negotiation API of Fumadocs for basic functionalities.
### Accept Markdown [#accept-markdown]
Serve markdown or HTML depending on the `Accept` header, this can improve the experience for AI agents.
```ts title="proxy.ts (Next.js)"
import { NextRequest, NextResponse } from 'next/server';
import { isMarkdownPreferred, rewritePath } from 'fumadocs-core/negotiation';
const { rewrite: rewriteLLM } = rewritePath('/docs/*path', '/llms.mdx/*path');
export default function proxy(request: NextRequest) {
if (isMarkdownPreferred(request)) {
const result = rewriteLLM(request.nextUrl.pathname);
if (result) {
return NextResponse.rewrite(new URL(result, request.nextUrl));
}
}
return NextResponse.next();
}
```
# Fumadocs Core (the core library of Fumadocs): Page Tree Utils
URL: /docs/headless/utils/page-tree
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/page-tree.mdx
Common utilities to interact with page tree.
## Usage [#usage]
See [Definitions](/docs/headless/page-tree) to learn more about Page Tree.
```ts
import {
findNeighbour,
findSiblings,
getPageTreeRoots,
findParent,
findPath,
type Root,
} from 'fumadocs-core/page-tree';
const pageTree: Root = {
// ...the root of page tree
};
// Get neighbours of a page
const neighbours = findNeighbour(pageTree, '/url/to/page');
// Get a list of root folders
const roots = getPageTreeRoots(pageTree);
// Get the sibling nodes of a page
const siblings = findSiblings(pageTree, '/url/to/page');
// Get the parent node of a page
const parent = findParent(pageTree, '/url/to/page');
// Find the path to the first matching node
const path = findPath(
pageTree.children,
// matcher
(node) => node.type === 'page' && node.url === '/url/to/page',
);
```
# Fumadocs Core (the core library of Fumadocs): Shiki (Internal)
URL: /docs/headless/utils/shiki
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/utils/shiki.mdx
Manage the Shiki instances.
## Overview [#overview]
Fumadocs use its own Shiki factory API to manage internal Shiki instances.
You can customize it for special purposes like using fine-grained bundles, for example:
```ts
import { createShikiFactory } from 'fumadocs-core/highlight/shiki';
export const myShikiFactory = createShikiFactory({
async init(options) {
const { createHighlighter, createJavaScriptRegexEngine } = await import('shiki');
return createHighlighter({
langs: [],
themes: [],
langAlias: options?.langAlias,
engine: createJavaScriptRegexEngine(),
});
},
});
```
Then pass it to different modules/features:
```tsx tab="Dynamic CodeBlock (UI)"
'use client';
import * as Base from 'fumadocs-ui/dynamic-codeblock.core';
export type DynamicCodeblockProps = Omit;
export function DynamicCodeBlock(props: DynamicCodeblockProps) {
return myShikiFactory.getOrInit()} {...props} />;
}
```
```ts tab="Rehype Code (Core)"
import { createRehypeCode } from 'fumadocs-core/mdx-plugins/rehype-code.core';
const rehypeCode = createRehypeCode(myShikiFactory);
```
# Fumadocs MDX (the built-in content source): Bun
URL: /docs/mdx/loader/bun
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/(integrations)/loader/bun.mdx
Access content in Bun.
## Setup [#setup]
Register the plugin in preload script:
```toml tab="bunfig.toml"
preload = ["./scripts/preload.ts"]
```
```ts tab="scripts/preload.ts"
import { createMdxPlugin } from 'fumadocs-mdx/bun';
Bun.plugin(createMdxPlugin());
```
It will add support for loading MDX/meta files on runtime.
Now running any script with Bun, you can access your content files directly.
### Re-generate `.source` folder [#re-generate-source-folder]
Optionally, you can re-generate the `.source` folder.
It is useful when the folder could be missing,
or you are using Vite, which defaults to generating code with Vite-specific APIs.
```ts title="preload.ts" tab="Next.js"
import { postInstall } from 'fumadocs-mdx/next';
await postInstall({ configPath: 'source.config.ts' });
```
```ts title="preload.ts" tab="Vite"
import { postInstall } from 'fumadocs-mdx/vite';
await postInstall({
configPath: 'source.config.ts',
index: {
target: 'bun',
},
});
```
# Fumadocs MDX (the built-in content source): Runtime Loader
URL: /docs/mdx/loader
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/(integrations)/loader/index.mdx
Fumadocs MDX loader integration.
## Introduction [#introduction]
By default, Fumadocs MDX requires a bundler to work.
When you are accessing your content without a bundler, such as:
- A script executed by Node.js or Bun.
- Any unbundled environment.
You will need a runtime loader. See below for available loader integrations.
## What is Next? [#what-is-next]
Define collections in your app modules with `fumadocs-mdx/macro`.
Define collections in `source.config.ts` with generated entry files.
Hit performance bottleneck? You can try lazy loading.
# Fumadocs MDX (the built-in content source): Vite
URL: /docs/mdx/vite
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/(integrations)/vite.mdx
Use Fumadocs MDX with Vite
## Setup [#setup]
Define collections in your app modules with `fumadocs-mdx/macro`.
Define collections in `source.config.ts` with generated entry files.
Hit performance bottleneck? You can try lazy loading.
# Fumadocs MDX (the built-in content source): Lazy Loading
URL: /docs/mdx/async
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/async.mdx
Configure lazy loading on collection outputs.
## Introduction [#introduction]
By default, all Markdown and MDX files need to be pre-compiled first. The same constraint also applies to the development server.
This may result in longer dev server start times for large docs sites. You can enable Async or Dynamic mode on doc collections to improve this.
## Async Mode [#async-mode]
Async mode will generate collection outputs using async imports.
```ts tab="Docs Collection"
import { defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
docs: {
// [!code ++]
async: true,
},
});
```
```ts tab="Doc Collection"
import { defineCollections } from 'fumadocs-mdx/config';
export const doc = defineCollections({
type: 'doc',
dir: 'content/docs',
// [!code ++]
async: true,
});
```
Depending on your bundler, this may reduce compilation time significantly on development server.
Turbopack doesn't support lazy bundling at the moment, async mode will only improve server
performance.
## Dynamic Mode [#dynamic-mode]
Dynamic mode works by performing **on-demand compilation**, then execute the output on runtime.
It is recommended to install & externalize `shiki`:
```npm
npm i shiki
```
Enable dynamic mode in collections like:
```ts tab="Docs Collection"
import { defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
docs: {
// [!code ++]
dynamic: true,
},
});
```
```ts tab="Doc Collection"
import { defineCollections } from 'fumadocs-mdx/config';
export const doc = defineCollections({
type: 'doc',
dir: 'content/docs',
// [!code ++]
dynamic: true,
});
```
Then, follow [Dynamic Entry](/docs/mdx/entry/dynamic) to access the collection from dynamic entry instead.
Dynamic mode comes with some limitations on MDX features.
- **No import/export allowed in MDX files.** For MDX components, pass them from the `components` prop instead.
- **Images must be referenced with URL (e.g. `/images/test.png`).** Don't use **file paths** like `./image.png`. You should locate your images in the `public` folder and reference them with URLs.
## Usage [#usage]
Frontmatter properties are still available on `page` object, but you need to invoke the `load()` async function to load the compiled content (and its exports).
For example:
```tsx title="page.tsx"
import { source } from '@/lib/source';
import { getMDXComponents } from '@/components/mdx';
const page = source.getPage(['...']);
if (page) {
// frontmatter properties are available
console.log(page.data);
// Markdown content requires await
const { body: MdxContent, toc } = await page.data.load();
console.log(toc);
return
,
}}
>
{children}
);
}
```
#### Decoration [#decoration]
Change the icon/styles of layout tabs.
```tsx
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
{chart}
`---[Icon]Label---` | a separator between two sections (icon supported). | | **Link** | `[Text](url)`
`[Icon][Text](url)`
`external:[Text](url)` | insert links (icon supported)
add a `external:` prefix to mark links as external. | | **Rest** | `...` | include remaining pages (sorted alphabetically). | | **Reversed Rest** | `z...a` | reversed **Rest** item. | | **Extract** | `...folder` | extract the items from a folder. | | **Except** | `!item` | Exclude an item from `...` or `z...a`. | ```json title="meta.json" { "pages": [ "components", "---My Separator---", "...folder", "...", "!file", "!otherFolder", "[Vercel](https://vercel.com)", "[Triangle][Vercel](https://vercel.com)" ] } ```
{items.map((item, i) => (
{i !== 0 &&
))}
);
}
```
You can use it by passing the page tree via `tree` prop in a server component.
### Breadcrumb Item [#breadcrumb-item]
### BreadcrumbItem
| Prop | Type | Description |
| ------ | ----------- | ----------- |
| `name` | `ReactNode` | |
| `url?` | `string` | |
# Fumadocs Core (the core library of Fumadocs): Components
URL: /docs/headless/components
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/components/index.mdx
Blocks for your docs
# Fumadocs Core (the core library of Fumadocs): Link
URL: /docs/headless/components/link
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/components/link.mdx
A Link component that handles external links
A component that wraps the Link component of your React framework (e.g. `next/link`) and automatically handles external links in the document.~
When an external URL is detected, it uses `` instead of the Link Component.
The `rel` property is automatically generated.
## Usage [#usage]
Usage is the same as using ``.
```mdx
import Link from 'fumadocs-core/link';
Click Me
```
### External [#external]
You can force a URL to be external by passing an `external` prop.
### Dynamic hrefs [#dynamic-hrefs]
You can enable dynamic hrefs by importing `dynamic-link`.
```mdx
import { DynamicLink } from 'fumadocs-core/dynamic-link';
always}>
On `always` mode, locale is stored as a cookie (set by the middleware), which isn't optimal for static sites.
This may cause undesired cache problems, and need to pay extra attention on SEO to ensure search engines can index your pages correctly.
code
),
depth: 2,
url: '#hello-code',
},
];
```
# Fumadocs Core (the core library of Fumadocs): MDX Plugins
URL: /docs/headless/mdx
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/index.mdx
Useful remark & rehype plugins for your docs.
# Fumadocs Core (the core library of Fumadocs): Package Install
URL: /docs/headless/mdx/install
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/install.mdx
Generate code blocks for installing packages
console...
```
## Usage [#usage]
Add the rehype plugin.
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { rehypeCode, type RehypeCodeOptions } from 'fumadocs-core/mdx-plugins';
const rehypeCodeOptions: RehypeCodeOptions = {
themes: {
light: 'github-light',
dark: 'github-dark',
},
};
await compile('...', {
rehypePlugins: [
// using default settings
rehypeCode,
// or with custom options
[rehypeCode, rehypeCodeOptions],
],
});
```
```ts tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
rehypeCodeOptions: {
// enabled by default on Fumadocs MDX
// configure options here
},
},
});
```
### Meta [#meta]
It parses the `title` meta string, and adds it to the `pre` element as an attribute.
````mdx tab="Input"
```js title="Title"
console.log('Hello');
```
````
```jsx tab="Output"
...``` You may filter the meta string before processing it with the `filterMetaString` option. ### Inline Code [#inline-code] You can enable it with `inline` option: ```ts import { type RehypeCodeOptions } from 'fumadocs-core/mdx-plugins'; const rehypeCodeOptions: RehypeCodeOptions = { // [!code ++] inline: 'tailing-curly-colon', }; ``` ```md title="Syntax" This is a highlighted inline code: `console.log("hello world"){:js}`. ``` This is a highlighted inline code: `console.log("hello world"){:js}`. ### Icon [#icon] The plugin will automatically adds an `icon` attribute according to the language meta string. It is a HTML string, you can render it with React `dangerouslySetInnerHTML`. ````md tab="Input" ```ts console.log('This should shows the logo of TypeScript'); ``` ```` ```jsx tab="Output"
...``` Disable or customize icons with the `icon` option. ### More Options [#more-options] The options are inherited from [Shiki](https://shiki.style), see their docs for other options. # Fumadocs Core (the core library of Fumadocs): Remark Admonition URL: /docs/headless/mdx/remark-admonition Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-admonition.mdx Use Admonition in Fumadocs In Docusaurus, there's an [Admonition syntax](https://docusaurus.io/docs/markdown-features/admonitions). For people migrating from Docusaurus, you can enable this remark plugin to support the Admonition syntax. ## Usage [#usage] It requires `remark-directive` to work. ```npm npm i remark-directive ``` Configure both plugins in your config. ```ts title="source.config.ts" tab="Fumadocs MDX" import remarkDirective from 'remark-directive'; import { remarkDirectiveAdmonition } from 'fumadocs-core/mdx-plugins'; import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { remarkPlugins: [remarkDirective, remarkDirectiveAdmonition], }, }); ``` ```ts tab="MDX Compiler" import remarkDirective from 'remark-directive'; import { remarkDirectiveAdmonition } from 'fumadocs-core/mdx-plugins'; import { compile } from '@mdx-js/mdx'; await compile('...', { remarkPlugins: [remarkDirective, remarkDirectiveAdmonition], }); ``` ### Example [#example] ```md tab="Input" :::tip[This is a `title`] Hello World ::: :::warning Hello World ::: ``` ```mdx tab="Output"
```
Where `./public/hello.png` points to the image in public directory.
### Example: Without Imports [#example-without-imports]
For Next.js, you can disable static imports on local images.
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [[remarkImage, { useImport: false }]],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
useImport: false,
},
},
});
```
```mdx
```
Yields:
```mdx
```
### Example: Relative Paths [#example-relative-paths]
When `useImport` is enabled, you can reference local images using relative paths.
```mdx
```
Be careful that using it with `useImport` disabled **doesn't work**.
Next.js will not add the image to public assets unless you have imported it in code.
For images in public directory, you can just reference them without relative paths.
### Example: Public Directory [#example-public-directory]
Customize the path of public directory
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
import path from 'node:path';
await compile('...', {
remarkPlugins: [[remarkImage, { publicDir: path.join(process.cwd(), 'dir') }]],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
import path from 'node:path';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
publicDir: path.join(process.cwd(), 'dir'),
},
},
});
```
You can pass a URL too.
```ts tab="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [[remarkImage, { publicDir: 'https://my-cdn.com/images' }]],
});
```
```ts title="source.config.ts" tab="Fumadocs MDX"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkImageOptions: {
publicDir: 'https://my-cdn.com/images',
},
},
});
```
# Fumadocs Core (the core library of Fumadocs): Remark LLMs
URL: /docs/headless/mdx/remark-llms
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-llms.mdx
Export the Markdown of your documents for LLMs.
The `remarkLLMs` plugin exports the Markdown of a document as `_markdown`, for LLMs. It keeps the Markdown you wrote, see [Stringification](/docs/headless/mdx/stringification) for how it's generated.
```mdx tab="Input"
import { Callout } from 'fumadocs-ui/components/callout';
## Getting Started
# Heading 1
## Sub Heading 1
## Sub Heading 2
# Heading 2
{children}
;
}
```
````
```tsx ts2js
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return {children}
;
}
```
# Fumadocs Core (the core library of Fumadocs): Stringification
URL: /docs/headless/mdx/stringification
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/stringification.mdx
How Fumadocs turns your documents into Markdown.
[Remark LLMs](/docs/headless/mdx/remark-llms) and [Remark Structure](/docs/headless/mdx/structure) output Markdown, for LLMs and search. Instead of stringifying the syntax tree, they slice your authored source:
- Markdown stays as you wrote it, nothing is escaped or reformatted.
- Remark plugins change it only by recording edits.
- It's fast, no syntax tree is serialized.
## How It Works [#how-it-works]
The output is the source of your document, with the edits of plugins applied. Nodes are located by their `position`:
- A node with a `position` outputs its source.
- A node without one, like those inserted by plugins, outputs nothing. Its plugin defines its Markdown instead.
For example, [Remark Image](/docs/headless/mdx/remark-image) turns `` into an ``---[Icon]Label---` | a separator between two sections (icon supported). | | **Link** | `[Text](url)`
`[Icon][Text](url)`
`external:[Text](url)` | insert links (icon supported)
add a `external:` prefix to mark links as external. | | **Rest** | `...` | include remaining pages (sorted alphabetically). | | **Reversed Rest** | `z...a` | reversed **Rest** item. | | **Extract** | `...folder` | extract the items from a folder. | | **Except** | `!item` | Exclude an item from `...` or `z...a`. | ```json title="meta.json" { "pages": [ "components", "---My Separator---", "...folder", "...", "!file", "!otherFolder", "[Vercel](https://vercel.com)", "[Triangle][Vercel](https://vercel.com)" ] } ```
Hello World
Some rich content.
...
;
}
```
A component that never calls it is kept as JSX syntax with its props, like:
```mdx
### Installation [#installation]
```npm
npm i fumadocs-mdx fumadocs-core @types/mdx
```
Add the plugin to Next.js config:
```js title="next.config.mjs"
import { createMDX } from 'fumadocs-mdx/next';
/** @type {import('next').NextConfig} */
const config = {
reactStrictMode: true,
};
// [!code ++:4]
const withMDX = createMDX();
// [!code highlight]
export default withMDX(config);
```
Fumadocs MDX is ESM-only, it's recommended to use `next.config.mjs` for accurate ESM resolution.
For TypeScript config file, it requires Native Node.js TypeScript Resolver, you can see [Next.js docs](https://nextjs.org/docs/app/api-reference/config/typescript#using-nodejs-native-typescript-resolver-for-nextconfigts) for details.
### Integrate with Fumadocs [#integrate-with-fumadocs]
Create a `lib/source.ts` file:
```ts title="lib/source.ts"
import { defineDocs } from 'fumadocs-mdx/macro';
import { loader } from 'fumadocs-core/source';
const docs = defineDocs({
dir: 'content/docs',
});
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
### Done [#done]
You can now write content in `content/docs` folder.
### Installation [#installation]
```npm
npm i fumadocs-mdx fumadocs-core @types/mdx
```
Add the Vite plugin:
```ts tab="Vite" title="vite.config.ts"
import { defineConfig } from 'vite';
import { fumadocsMdx } from 'fumadocs-mdx/vite';
export default defineConfig({
plugins: [
// [!code ++]
fumadocsMdx(),
// ...
],
});
```
```ts tab="Waku" title="waku.config.ts"
import { type Config, defineConfig } from 'waku/config';
import { fumadocsMdx } from 'fumadocs-mdx/vite';
import type { UserConfig } from 'vite';
export default defineConfig({
vite: {
plugins: [
// [!code ++]
fumadocsMdx(),
],
resolve: {
tsconfigPaths: true,
},
} satisfies UserConfig as Config['vite'],
});
```
### Integrate with Fumadocs [#integrate-with-fumadocs]
Create a `lib/source.ts` file:
```ts title="app/lib/source.ts"
import { defineDocs } from 'fumadocs-mdx/macro';
import { loader } from 'fumadocs-core/source';
const docs = defineDocs({
dir: 'content/docs',
});
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
### Done [#done]
You can now write content in `content/docs` folder.
## What is Next? [#what-is-next]
Selecting an option navigates to the same page in that root folder, or its index page when the page doesn't exist there. See [Versioning](/docs/navigation#versioning) for a complete example.
### Sidebar Components [#sidebar-components]
You can replace certain components for rendering page tree.
```tsx tab="layout.tsx"
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { SidebarSeparator } from './layout.client';