{/* pass MDX components and render it */}
);
}
```
# Fumadocs MDX (the built-in content source): Performance
URL: /docs/mdx/performance
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/performance.mdx
The performance of Fumadocs MDX
***
title: Performance
description: The performance of Fumadocs MDX
icon: Rocket
------------
## Overview
Fumadocs MDX is a bundler plugin, in other words, it has a higher performance bottleneck.
With bundlers like Webpack and Turbopack, it is enough for large docs sites with nearly 500+ MDX files, which is sufficient for almost all use cases.
Since Fumadocs MDX works with your bundler, you can import any files including client components in your MDX files.
This allows high flexibility and ensures everything is optimized by default.
### Image Optimization
Fumadocs MDX resolves images into static imports with [Remark Image](/docs/headless/mdx/remark-image).
Therefore, your images will be optimized automatically for your React framework (e.g. Next.js Image API).
```mdx
or in public folder
```
Yields:
```mdx
import HelloImage from './hello.png';
Good Heading
{items.map((item, i) => (
{i !== 0 && (
))}
);
}
```
You can use it by passing the page tree via `tree` prop in a server component.
### Breadcrumb Item
code
),
depth: 2,
url: '#hello-code',
},
];
```
# Fumadocs Core (core library of framework): 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.
***
title: MDX Plugins
index: true
description: Useful remark & rehype plugins for your docs.
----------------------------------------------------------
# Fumadocs Core (core library of framework): 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
***
title: Package Install
description: Generate code blocks for installing packages
---------------------------------------------------------
...
```
### Meta
It parses the `title` meta string, and adds it to the `pre` element as an attribute.
````mdx
```js title="Title"
console.log('Hello');
```
````
You may filter the meta string before processing it with the `filterMetaString` option.
### Inline Code
`console.log("hello world"){:js}` works.
See [https://shiki.style/packages/rehype#inline-code](https://shiki.style/packages/rehype#inline-code).
### Icon
Adds an icon according to the language of the codeblock.
It outputs HTML, you might need to render it with React `dangerouslySetInnerHTML`.
```jsx
...``` Disable or customise icons with the `icon` option. ### More Options See [Shiki](https://shiki.style). # Fumadocs Core (core library of framework): 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 *** title: Remark Admonition description: 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 ```ts title="source.config.ts" tab="Fumadocs MDX" import { remarkAdmonition } from 'fumadocs-core/mdx-plugins'; import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { remarkPlugins: [remarkAdmonition], }, }); ``` ```ts tab="MDX Compiler" import { compile } from '@mdx-js/mdx'; import { remarkAdmonition } from 'fumadocs-core/mdx-plugins'; await compile('...', { remarkPlugins: [remarkAdmonition], }); ``` ### Input ```md :::warning Hello World ::: ``` ### Output ```mdx
```
Where `./public/hello.png` points to the image in public directory.
### Example: Without Imports
For Next.js, you can disable static imports on local images.
```ts
import { remarkImage } from 'fumadocs-core/mdx-plugins';
export default {
remarkPlugins: [[remarkImage, { useImport: false }]],
};
```
```mdx
```
Yields:
```mdx
```
### 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
Customise the path of public directory
```ts
import { remarkImage } from 'fumadocs-core/mdx-plugins';
import path from 'node:path';
export default {
remarkPlugins: [
remarkImage,
{
publicDir: path.join(process.cwd(), 'dir'),
},
],
};
```
You can pass a URL too.
```ts
import { remarkImage } from 'fumadocs-core/mdx-plugins';
export default {
remarkPlugins: [
remarkImage,
{
publicDir: 'https://my-cdn.com/images',
},
],
};
```
# Fumadocs Core (core library of framework): Remark Files
URL: /docs/headless/mdx/remark-mdx-files
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-mdx-files.mdx
Generate files from codeblocks.
***
title: Remark Files
description: Generate files from codeblocks.
--------------------------------------------
## Introduction
This plugin takes a codeblock like:
````md
```files
project
├── src
│ ├── index.js
│ └── utils
│ └── helper.js
├── package.json
```
````
and convert into:
```mdx
{children}
;
}
```
````
```tsx ts2js
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return {children}
;
}
```
# Fumadocs Core (core library of framework): 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 information from your documents, useful for implementing document search
***
title: Remark Structure
description: Extract information from your documents, useful for implementing document search
---------------------------------------------------------------------------------------------
## Usage
Add it as a remark plugin.
```ts title="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkStructure } from 'fumadocs-core/mdx-plugins';
const vfile = await compile('...', {
remarkPlugins: [remarkStructure],
});
```
> This plugin is included by default on Fumadocs MDX.
Extracted information could be found in `vfile.data.structuredData`, you may
write your own plugin to convert it into a MDX export.
### Options
### Hello World
```
### Hello World
You no longer need to use the step component anymore.
# Fumadocs Framework: Tabs
URL: /docs/ui/components/tabs
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/tabs.mdx
A Tabs component built with Radix UI, with additional features such as persistent and shared value.
***
title: Tabs
description:
A Tabs component built with Radix UI, with additional features such as
persistent and shared value.
preview: tabs
-------------
lang dynamic segment?}>
If you're using another name like `app/[locale]`, you also need to update `generateStaticParams()` in docs page:
```tsx
export function generateStaticParams() {
return source.generateParams(); // [!code --]
return source.generateParams('slug', 'locale'); // [!code ++] new param name
}
```
```tsx
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
const base = baseOptions();
return (
This heading looks good!
It applies the Typography styles, wrap your content here.Page Not Found
The page you are looking for does not exist.
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
````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');
```
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 }}
/>
);
}
```
> This is originally inspired by [remark-mermaid](https://github.com/the-guild-org/docs/blob/main/packages/remark-mermaid/src/mermaid.tsx).
Add the component as a MDX component:
```tsx title="mdx-components.tsx"
import defaultMdxComponents from 'fumadocs-ui/mdx';
import { Mermaid } from '@/components/mdx/mermaid';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents): MDXComponents {
return {
...defaultMdxComponents,
Mermaid, // [!code ++]
...components,
};
}
```
## Usage
Use it in MDX files.
```mdx
### 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: Twoslash
URL: /docs/ui/markdown/twoslash
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/markdown/twoslash.mdx
Use Typescript Twoslash in your docs
***
title: Twoslash
description: Use Typescript Twoslash in your docs
-------------------------------------------------
## 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.
npm
pnpm
yarn
bun
```bash
npm install fumadocs-twoslash twoslash
```
```bash
pnpm add fumadocs-twoslash twoslash
```
```bash
yarn add fumadocs-twoslash twoslash
```
```bash
bun add fumadocs-twoslash twoslash
```
For Next.js, you need to externalize the following deps:
```js title="next.config.mjs (Next.js)"
const config = {
reactStrictMode: true,
// [!code ++]
serverExternalPackages: ['typescript', 'twoslash'],
};
```
Add to your Shiki transformers.
```ts twoslash 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(),
],
},
},
});
```
Add styles, Tailwind CSS v4 is required.
```css title="Tailwind CSS"
@import 'fumadocs-twoslash/twoslash.css';
```
Add MDX components.
```tsx title="mdx-components.tsx"
import * as Twoslash from 'fumadocs-twoslash/ui';
import defaultComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents): MDXComponents {
return {
...defaultComponents,
...Twoslash,
...components,
};
}
```
Now you can add `twoslash` meta string to codeblocks.
````md
```ts twoslash
console.log('Hello World');
```
````
### Example
Learn more about [Twoslash notations](https://twoslash.netlify.app/refs/notations).
```ts twoslash title="Test" lineNumbers
type Player = {
/**
* The player name
* @default 'user'
*/
name: string;
};
// ---cut---
// @noErrors
console.g;
// ^|
const player: Player = { name: 'Hello World' };
// ^?
```
```ts twoslash
const a = '123';
console.log(a);
// ^^^
```
```ts twoslash
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
input: ['./museum.yaml'],
output: './content/docs/ui',
});
```
```ts twoslash
// @errors: 2588
const a = '123';
a = 132;
```
## Cache
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(),
});
```
# Fumadocs Framework: Code Block
URL: /docs/ui/mdx/codeblock
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/mdx/codeblock.mdx
Displaying Shiki highlighted code blocks
***
title: Code Block
description: Displaying Shiki highlighted code blocks
-----------------------------------------------------
),
...components,
};
}
```
See [Markdown](/docs/ui/markdown#codeblock) for usages.
### Keep Background
Use the background color generated by Shiki.
```tsx
import { Pre, CodeBlock } from 'fumadocs-ui/components/codeblock';
;
```
### Icons
Specify a custom icon by passing an `icon` prop to `CodeBlock` component.
By default, the icon will be injected by the custom Shiki transformer.
```js title="config.js"
console.log('js');
```
# Fumadocs Framework: MDX
URL: /docs/ui/mdx
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/mdx/index.mdx
Default MDX Components
***
title: MDX
description: Default MDX Components
-----------------------------------
## Usage
The default MDX components include Cards, Callouts, Code Blocks and Headings.
```ts
import defaultMdxComponents from 'fumadocs-ui/mdx';
```
### Relative Link
To support links with relative file path in `href`, override the default `a` component with:
```tsx title="app/docs/[[...slug]]/page.tsx"
import { createRelativeLink } from 'fumadocs-ui/mdx';
import { source } from '@/lib/source';
import { getMDXComponents } from '@/mdx-components';
const page = source.getPage(['...']);
return (
Server Component only.
# Fumadocs Framework: Navigation
URL: /docs/ui/navigation
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/navigation/index.mdx
Configure navigation in your Fumadocs app.
***
title: Navigation
description: Configure navigation in your Fumadocs app.
index: true
-----------
# Fumadocs Framework: Layout Links
URL: /docs/ui/navigation/links
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/navigation/links.mdx
Customise the shared navigation links on all layouts.
***
title: Layout Links
description: Customise the shared navigation links on all layouts.
------------------------------------------------------------------
## Overview
Fumadocs allows adding additional links to your layouts with a `links` prop, like linking to your "showcase" page.
{children}
);
}
```
```tsx tab="Home Layout" title="app/(home)/layout.tsx"
import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { baseOptions } from '@/lib/layout.shared';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
You can see all supported items below:
### Link Item
A link to navigate to a URL/href, can be external.
```tsx title="lib/layout.shared.tsx"
import { BookIcon } from 'lucide-react';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
export function baseOptions(): BaseLayoutProps {
return {
links: [
{
icon:
Documentation
Hello World
),
},
// other items
]}
>
{children}
);
}
```
# Fumadocs Framework: Sidebar Links
URL: /docs/ui/navigation/sidebar
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/navigation/sidebar.mdx
Customise sidebar navigation links on Docs Layout.
***
title: Sidebar Links
description: Customise sidebar navigation links on Docs Layout.
---------------------------------------------------------------
## Overview
{children}
);
}
```
You may hardcode it too:
```tsx title="layout.tsx"
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
### Sidebar Tabs (Dropdown) \[#sidebar-tabs]
Sidebar Tabs are folders with tab-like behaviours, only the content of opened tab will be visible.
You can specify a `banner` to the [Docs Layout](/docs/ui/layouts/docs) component.
```tsx
import { DocsLayout, type DocsLayoutProps } from 'fumadocs-ui/layouts/docs';
import type { ReactNode } from 'react';
import { baseOptions } from '@/lib/layout.shared';
import { source } from '@/lib/source';
const docsOptions: DocsLayoutProps = {
...baseOptions(),
tree: source.pageTree,
sidebar: {
banner: {children} ;
}
```
#### Decoration
Change the icon/styles of tabs.
```tsx
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
({
...option,
icon:
Search powered by Algolia
);
}
```
`useDocsSearch()` doesn't use instant search (their official
Javascript client).
### Replace Search Dialog
Replace the search dialog with yours from `
{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
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 { useDocsSearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const { search, setSearch, query } = useDocsSearch({
tag, // [!code ++]
// other options depending on your search engine
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs Framework: Search
URL: /docs/ui/search
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/search/index.mdx
Implement document search in your docs
***
title: Search
description: Implement document search in your docs
---------------------------------------------------
## Search UI
You can customise some configurations from root provider.
For example, to disable search UI:
```tsx title="app/layout.tsx"
import { RootProvider } from 'fumadocs-ui/provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
### Hot Keys
Customise the hot keys to trigger search dialog, by default it's ⌘ K or Ctrl K.
```tsx
import { RootProvider } from 'fumadocs-ui/provider';
{children}
;
```
## Search Client
You can choose & configure the search client according to your search engine, it defaults to Orama search.
(
{
// ...
}}
/>
)}
/>
```
# Fumadocs Framework: Mixedbread
URL: /docs/ui/search/mixedbread
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/search/mixedbread.mdx
Using Mixedbread with Fumadocs UI.
***
title: Mixedbread
description: Using Mixedbread with Fumadocs UI.
-----------------------------------------------
## Overview
For the setup guide, see [Integrate Mixedbread Search](/docs/headless/search/mixedbread).
## Setup
Create a search dialog, replace `apiKey` and `vectorStoreId` 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 { useDocsSearch } from 'fumadocs-core/search/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
import Mixedbread from '@mixedbread/sdk';
const client = new Mixedbread({
apiKey: 'mxb_xxxx',
baseURL: 'https://api.example.com', // Optional, defaults to https://api.mixedbread.com
});
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const { search, setSearch, query } = useDocsSearch({
type: 'mixedbread',
client,
vectorStoreId: 'vectorStoreId',
locale,
});
return (
Search powered by Mixedbread
);
}
```
### Replace Search Dialog
Replace the search dialog with yours from `
{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
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 { useDocsSearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const { search, setSearch, query } = useDocsSearch({
tag, // [!code ++]
// other options depending on your search engine
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# Fumadocs Framework: Orama Cloud
URL: /docs/ui/search/orama-cloud
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/search/orama-cloud.mdx
Using Orama Cloud with Fumadocs UI.
***
title: Orama Cloud
description: Using Orama Cloud with Fumadocs UI.
------------------------------------------------
## Setup
For the setup guide, see [Integrate Orama Cloud](/docs/headless/search/orama-cloud).
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 { useDocsSearch } from 'fumadocs-core/search/client';
import { OramaClient } from '@oramacloud/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
const client = new OramaClient({
endpoint: 'Endpoint URL',
api_key: 'API Key',
});
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const { search, setSearch, query } = useDocsSearch({
type: 'orama-cloud',
client,
locale,
});
return (
Search powered by Orama
);
}
```
### Replace Search Dialog
Replace the search dialog with yours from `
{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: Orama (default)
URL: /docs/ui/search/orama
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/search/orama.mdx
The default search engine powered by Orama.
***
title: Orama (default)
description: The default search engine powered by Orama.
--------------------------------------------------------
## Overview
Fumadocs configures [Orama 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
Create a search dialog.
The UI has been configured by default, you can also re-create it for further customisations:
```tsx title="components/search.tsx"
'use client';
import { useDocsSearch } 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, setSearch, query } = useDocsSearch({
type: 'fetch',
locale,
});
return (
);
}
```
For Static Export, you can configure [static mode](/docs/headless/search/orama#static-export) on search server, and use the `static` client:
npm
pnpm
yarn
bun
```bash
npm install @orama/orama
```
```bash
pnpm add @orama/orama
```
```bash
yarn add @orama/orama
```
```bash
bun add @orama/orama
```
```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 { useDocsSearch } from 'fumadocs-core/search/client';
import { create } from '@orama/orama';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
function initOrama() {
return create({
schema: { _: 'string' },
// https://docs.orama.com/docs/orama-js/supported-languages
language: 'english',
});
}
export default function DefaultSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const { search, setSearch, query } = useDocsSearch({
type: 'static',
initOrama,
locale,
});
return (
);
}
```
### Replace Search Dialog
Replace the search dialog with yours from `
{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
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 { useDocsSearch } from 'fumadocs-core/search/client';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const { search, setSearch, query } = useDocsSearch({
tag, // [!code ++]
// other options depending on your search engine
});
return (
...
{/* [!code ++:3] */}
My Value
);
}
```
# 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.
***
title: Bun
description: Access content in Bun.
-----------------------------------
## 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());
```
Now running any script with Bun will automatically support accessing your content files.
# Fumadocs MDX (the built-in content source): 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.
***
title: Loader
description: Fumadocs MDX loader integration.
---------------------------------------------
## 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.
* **Config files:** config files like `react-router.config.ts` are executed without a bundler.
* Any unbundled environment.
You will need a runtime loader. See below for available loader integrations.
npm
pnpm
yarn
bun
```bash
npm i fumadocs-mdx fumadocs-core @types/mdx
```
```bash
pnpm add fumadocs-mdx fumadocs-core @types/mdx
```
```bash
yarn add fumadocs-mdx fumadocs-core @types/mdx
```
```bash
bun add fumadocs-mdx fumadocs-core @types/mdx
```
Create the configuration file:
```ts title="source.config.ts"
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
export default defineConfig();
```
Add the Vite plugin:
```ts title="vite.config.ts"
import { reactRouter } from '@react-router/dev/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';
import tsconfigPaths from 'vite-tsconfig-paths';
import mdx from 'fumadocs-mdx/vite';
import * as MdxConfig from './source.config';
export default defineConfig({
plugins: [mdx(MdxConfig), tailwindcss(), reactRouter(), tsconfigPaths()],
});
```
### Integrate with Fumadocs
To integrate with Fumadocs, make a `lib/source.ts` file:
```ts title="app/lib/source.ts"
import { loader } from 'fumadocs-core/source';
import { create, docs } from '../../source.generated';
export const source = loader({
source: await create.sourceAsync(docs.doc, docs.meta),
baseUrl: '/docs',
});
```
The `source.generated.ts` file will be generated when you run development server or production build.
### Done
The configuration is now finished.
## Examples
### Rendering Content
As React Router doesn't support RSC at the moment, use `toClientRenderer()` to lazy load MDX content as a component on browser.
For example:
```tsx
import type { Route } from './+types/page';
import { source } from '@/lib/source';
import { docs } from '../../source.generated';
import { toClientRenderer } from 'fumadocs-mdx/runtime/vite';
export async function loader({ params }: Route.LoaderArgs) {
const slugs = params['*'].split('/').filter((v) => v.length > 0);
const page = source.getPage(slugs);
if (!page) throw new Response('Not found', { status: 404 });
return {
path: page.path,
};
}
const renderer = toClientRenderer(docs.doc, ({ default: Mdx, frontmatter }) => {
return (
npm
pnpm
yarn
bun
```bash
npm i fumadocs-mdx fumadocs-core @types/mdx
```
```bash
pnpm add fumadocs-mdx fumadocs-core @types/mdx
```
```bash
yarn add fumadocs-mdx fumadocs-core @types/mdx
```
```bash
bun add fumadocs-mdx fumadocs-core @types/mdx
```
Create the configuration file:
```ts title="source.config.ts"
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
export default defineConfig();
```
Add the Vite plugin:
```ts title="vite.config.ts"
import react from '@vitejs/plugin-react';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { defineConfig } from 'vite';
import tsConfigPaths from 'vite-tsconfig-paths';
import tailwindcss from '@tailwindcss/vite';
import mdx from 'fumadocs-mdx/vite';
export default defineConfig({
server: {
port: 3000,
},
plugins: [
mdx(await import('./source.config')),
tailwindcss(),
tsConfigPaths({
projects: ['./tsconfig.json'],
}),
tanstackStart({
customViteReactPlugin: true,
prerender: {
enabled: true,
},
}),
react(),
],
});
```
### Integrate with Fumadocs
To integrate with Fumadocs, create a `lib/source.ts` file:
```ts title="src/lib/source.ts"
import { loader } from 'fumadocs-core/source';
import { create, docs } from '../../source.generated';
export const source = loader({
source: await create.sourceAsync(docs.doc, docs.meta),
baseUrl: '/docs',
});
```
The `source.generated.ts` file will be generated when you run development server or production build.
### Done
The configuration is now finished.
## Examples
### Rendering Content
As Tanstack Start doesn't support RSC at the moment, use `createClientLoader()` to lazy load MDX content as a component on browser.
For example:
```tsx title="src/routes/docs/$.tsx"
import { createFileRoute, notFound } from '@tanstack/react-router';
import { createServerFn } from '@tanstack/react-start';
import { source } from '@/lib/source';
import { docs } from '../../../source.generated';
import { createClientLoader } from 'fumadocs-mdx/runtime/vite';
export const Route = createFileRoute('/docs/$')({
component: Page,
loader: async ({ params }) => {
const data = await loader({ data: params._splat?.split('/') ?? [] });
await clientLoader.preload(data.path);
return data;
},
});
const loader = createServerFn({
method: 'GET',
})
.validator((slugs: string[]) => slugs)
.handler(async ({ data: slugs }) => {
const page = source.getPage(slugs);
if (!page) throw notFound();
return {
path: page.path,
};
});
const clientLoader = createClientLoader(docs.doc, {
id: 'docs',
component({ frontmatter, default: MDX }) {
return (
npm
pnpm
yarn
bun
```bash
npm i fumadocs-mdx fumadocs-core fumadocs-ui @types/mdx
```
```bash
pnpm add fumadocs-mdx fumadocs-core fumadocs-ui @types/mdx
```
```bash
yarn add fumadocs-mdx fumadocs-core fumadocs-ui @types/mdx
```
```bash
bun add fumadocs-mdx fumadocs-core fumadocs-ui @types/mdx
```
Create the configuration file:
```ts title="source.config.ts"
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
export default defineConfig();
```
Add the Vite plugin:
```ts title="vite.config.ts"
import { defineConfig } from 'waku/config';
import mdx from 'fumadocs-mdx/vite';
import * as MdxConfig from './source.config.js';
import tailwindcss from '@tailwindcss/vite';
import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
vite: {
plugins: [tailwindcss(), mdx(MdxConfig), tsconfigPaths()],
},
});
```
### Integrate with Fumadocs
Create a `lib/source.ts` file:
```ts title="src/lib/source.ts"
import { loader } from 'fumadocs-core/source';
import { create, docs } from '../../source.generated.js';
export const source = loader({
source: await create.sourceAsync(docs.doc, docs.meta),
baseUrl: '/docs',
});
```
The `source.generated.ts` file will be generated when you run development server or production build.
### Done
Have fun!
## Examples
### Rendering Pages
Since Waku supports RSC, you can use the exported `default` component directly.
```tsx
import { source } from '@/lib/source';
import type { PageProps } from 'waku/router';
import defaultMdxComponents from 'fumadocs-ui/mdx';
import {
DocsBody,
DocsDescription,
DocsPage,
DocsTitle,
} from 'fumadocs-ui/page';
export default async function DocPage({
slugs,
}: PageProps<'/docs/[...slugs]'>) {
const page = source.getPage(slugs);
if (!page) {
// ...
}
const MDX = page.data.default;
return (
{page.data.title}
{page.data.description}
);
}
```
# Fumadocs Framework: Configurations
URL: /docs/ui/openapi/configurations
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/(integrations)/openapi/configurations.mdx
Customise Fumadocs OpenAPI
***
title: Configurations
description: Customise Fumadocs OpenAPI
---------------------------------------
## File Generator
Pass options to the `generateFiles` function.
### Input
* OpenAPI Server object.
* anything supported by [`input`](#input-1).
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
input: ['./unkey.json'],
});
```
### Output
The output directory.
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
output: '/content/docs',
});
```
### Per
Customise how the page is generated, default to `operation`.
Operation refers to an API endpoint with specific method like
`/api/weather:GET`.
| mode | | output |
| --------- | --------------------------- | ------------------------------------- |
| tag | operations with same tag | `{tag_name}.mdx` |
| file | operations in schema schema | `{file_name}.mdx` |
| operation | each operation | `{operationId ?? endpoint_path}.mdx`) |
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
per: 'tag',
});
```
### Group By
In `operation` mode, you can group output files with folders.
| value | output |
| ----- | ------------------------------------------------------ |
| tag | `{tag}/{operationId ?? endpoint_path}.mdx` |
| route | `{endpoint_path}/{method}.mdx` (ignores `name` option) |
| none | `{operationId ?? endpoint_path}.mdx` (default) |
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
per: 'operation',
groupBy: 'tag',
});
```
### Index
Generate index files with cards linking to generated pages.
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
input: ['./petstore.yaml', './museum.yaml'],
output: './content/docs',
index: {
// for generating `href`
url: {
baseUrl: '/docs',
contentDir: './content/docs',
},
items: [
{
path: 'index.mdx',
// optional: restrict the input files
only: ['petstore.yaml'],
// optional: set frontmatter
description: 'All available pages',
},
],
},
});
```
### Imports
Add custom imports to generated MDX files. This is useful for including components, utilities, or other dependencies in your generated documentation.
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
input: ['./petstore.yaml'],
output: './content/docs',
imports: [
{
names: ['CustomComponent', 'AnotherComponent'],
from: '@/components/custom',
},
{
names: ['utils'],
from: '@/lib/utils',
},
{
names: ['API_BASE_URL'],
from: '@/constants',
},
],
});
```
This will add the following imports to all generated MDX files:
```ts
import { CustomComponent, AnotherComponent } from '@/components/custom';
import { utils } from '@/lib/utils';
import { API_BASE_URL } from '@/constants';
```
The `imports` configuration is especially important for Cards generation in
index files, where you need to import `source` and `getPageTreePeers` for the
navigation functionality to work.
### Name
A function that controls the output path of MDX pages.
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
name: (output, document) => {
if (output.type === 'operation') {
const operation = document.paths![output.item.path]![output.item.method]!;
// operation object
console.log(operation);
return 'my-dir/filename';
}
const hook = document.webhooks![output.item.name][output.item.method]!;
// webhook object
console.log(hook);
return 'my-dir/filename';
},
});
```
### Frontmatter
Customise the frontmatter of MDX files.
By default, it includes:
| property | description |
| ------------- | ------------------------------------------------ |
| `title` | Page title |
| `description` | Page description |
| `full` | Always true, added for Fumadocs UI |
| `method` | Available method of operation (`operation` mode) |
| `route` | Route of operation (`operation` mode) |
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
input: ['./petstore.yaml'],
output: './content/docs',
frontmatter: (title, description) => ({
myProperty: 'hello',
}),
});
```
### Add Generated Comment
Add a comment to the top of generated files indicating they are auto-generated.
```ts
import { generateFiles } from 'fumadocs-openapi';
void generateFiles({
input: ['./petstore.yaml'],
output: './content/docs',
// Add default comment
addGeneratedComment: true,
// Or provide a custom comment
addGeneratedComment: 'Custom auto-generated comment',
// Or disable comments
addGeneratedComment: false,
});
```
### Tag Display Name
Adding `x-displayName` to OpenAPI Schema can control the display name of your tags.
```yaml title="openapi.yaml"
tags:
- name: test
description: this is a tag.
x-displayName: My Test Name
```
## OpenAPI Server
The server to render pages.
### Input
* File Paths
* External URLs
* A function (see below)
```ts tab="Basic"
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
input: ['./unkey.json'],
});
```
```ts tab="Function"
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
async input() {
return {
// [id]: downloaded OpenAPI Schema
my_schema: await fetch(
'https://registry.scalar.com/@scalar/apis/galaxy/latest?format=json',
).then((res) => res.json()),
};
},
});
```
### Generate Code Samples
Generate custom code samples for each API endpoint. Make sure to install the types package to give you type-safety when customising it:
npm
pnpm
yarn
bun
```bash
npm install openapi-types -D
```
```bash
pnpm add openapi-types -D
```
```bash
yarn add openapi-types --dev
```
```bash
bun add openapi-types --dev
```
```ts
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
generateCodeSamples(endpoint) {
return [
{
lang: 'js',
label: 'JavaScript SDK',
source: "console.log('hello')",
},
];
},
});
```
In addition, you can also specify code samples via OpenAPI schema.
```yaml
paths:
/plants:
get:
x-codeSamples:
- lang: js
label: JavaScript SDK
source: |
const planter = require('planter');
planter.list({ unwatered: true });
```
#### Disable Code Sample
You can disable the code sample for a specific language, for example, to disable cURL:
```ts
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
generateCodeSamples(endpoint) {
return [
{
lang: 'curl',
label: 'cURL',
source: false,
},
];
},
});
```
### Renderer
Customise components in the page.
```ts
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
renderer: {
Root(props) {
// your own (server) component
},
},
});
```
# Fumadocs Framework: OpenAPI
URL: /docs/ui/openapi
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/(integrations)/openapi/index.mdx
Generating docs for OpenAPI schema
***
title: OpenAPI
description: Generating docs for OpenAPI schema
-----------------------------------------------
It only works under RSC environments.
## Manual Setup
Install the required packages.
npm
pnpm
yarn
bun
```bash
npm i fumadocs-openapi shiki
```
```bash
pnpm add fumadocs-openapi shiki
```
```bash
yarn add fumadocs-openapi shiki
```
```bash
bun add fumadocs-openapi shiki
```
If you encountered any issues, please check
[#2223](https://github.com/fuma-nama/fumadocs/issues/2223).
### 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-openapi/css/preset.css';
```
### Configure Pages
Create an OpenAPI instance on the server.
```ts title="lib/openapi.ts"
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
// the OpenAPI schema, you can also give it an external URL.
input: ['./unkey.json'],
});
```
```ts title="lib/source.ts"
import { transformerOpenAPI } from 'fumadocs-openapi/server';
import { loader } from 'fumadocs-core/source';
export const source = loader({
// [!code ++:3] adds a badge to each page item in page tree
pageTree: {
transformers: [transformerOpenAPI()],
},
});
```
Add `APIPage` to your MDX Components, so that you can use it in MDX files.
```tsx title="mdx-components.tsx"
import defaultComponents from 'fumadocs-ui/mdx';
import { APIPage } from 'fumadocs-openapi/ui';
import { openapi } from '@/lib/openapi';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents): MDXComponents {
return {
...defaultComponents,
APIPage: (props) =>
Do not use this on unreliable sites and API endpoints, the proxy server will
forward all received headers & body, including HTTP-only `Cookies` and
`Authorization` header.
### Setup
Create a route handler for proxy server.
```ts title="/api/proxy/route.ts"
import { openapi } from '@/lib/openapi';
export const { GET, HEAD, PUT, POST, PATCH, DELETE } = openapi.createProxy({
// optional, we recommend to set a list of allowed origins for proxied requests
allowedOrigins: ['https://example.com'],
});
```
> Follow the [Getting Started](/docs/ui/openapi) guide if `openapi` server is not yet configured.
And enable the proxy from `createOpenAPI`.
```ts title="lib/source.ts"
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
proxyUrl: '/api/proxy', // [!code ++]
});
```
```js title="config.js"
import createMDX from 'fumadocs-mdx/config';
const withMDX = createMDX();
// [!code word:config]
/** @type {import('next').NextConfig} */
const config = {
// [!code highlight]
reactStrictMode: true, // [!code highlight]
}; // [!code highlight]
export default withMDX(config);
```
{props.children} {/* [!code highlight] */}
{props.children}
<>
<>
```tsx tab="Shared Options" title="lib/layout.shared.tsx"
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
export function baseOptions(): BaseLayoutProps {
return {
links: [], // [!code highlight]
// other options}
};
}
```
```tsx tab="Docs Layout" title="app/docs/layout.tsx"
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';
import { source } from '@/lib/source';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
Sidebar items are rendered from the page tree you passed to `
By default, the tab trigger will be displayed as a **Dropdown** component (hidden unless one of its items is active).
You can add items by marking folders as [Root Folders](/docs/ui/page-conventions#root-folder), create a `meta.json` file in the folder:
```json title="content/docs/my-folder/meta.json"
{
"title": "Name of Folder",
"description": "The description of root folder (optional)",
"root": true
}
```
Or specify them explicitly:
```tsx title="/app/docs/layout.tsx"
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
Hello World
,
},
};
export default function Layout({ children }: { children: ReactNode }) {
return