Good Heading
### Search [#search-step]
#### Built-in Search [#built-in-search]
1. [Configure Search Server](/docs/headless/search/orama#static-export).
2. [Configure Search UI/Client](/docs/search/orama#static).
After the configurations, your app will statically store the search indexes, and search will be computed on browser instead.
#### Cloud Solutions [#cloud-solutions]
Since the search functionality is powered by remote servers, static export works without configuration.
### Deployment [#deployment-step]
#### Next.js [#nextjs]
You can enable Next.js static export, it allows you to export the app as a static HTML site without a Node.js server.
```js title="next.config.mjs"
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
output: 'export',
// Optional: Change links `/me` -> `/me/` and emit `/me.html` -> `/me/index.html`
// trailingSlash: true,
// Optional: Prevent automatic `/me` -> `/me/`, instead preserve `href`
// skipTrailingSlashRedirect: true,
};
```
See [Next.js docs](https://nextjs.org/docs/app/guides/static-exports) for limitations and details.
#### React Router [#react-router]
By configuring SPA mode, you can serve the `build/client` directory as a static website.
On SPA mode, all your server-side loaders must be pre-rendered.
See [React Router Docs](https://reactrouter.com/how-to/spa) for details.
```ts title="react-router.config.ts"
import type { Config } from '@react-router/dev/config';
import { glob } from 'node:fs/promises';
import { createGetUrl, getSlugs } from 'fumadocs-core/source';
const getUrl = createGetUrl('/docs');
export default {
// disable SSR [!code highlight]
ssr: false,
// [!code ++:9]
async prerender({ getStaticPaths }) {
const paths: string[] = [...getStaticPaths()];
for await (const entry of glob('**/*.mdx', { cwd: 'content/docs' })) {
paths.push(getUrl(getSlugs(entry)));
}
return paths;
},
} satisfies Config;
```
#### Tanstack Start [#tanstack-start]
Configure SPA mode and pre-rendering, refer to [SPA Mode](https://tanstack.com/start/latest/docs/framework/react/guide/spa-mode) for deploying SPA apps with Tanstack Start.
```ts title="vite.config.ts"
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
// ...other plugins
tanstackStart({
spa: {
enabled: true,
// Tanstack Router will automatically crawl your pages [!code ++:4]
prerender: {
enabled: true,
},
// if you have any hidden paths that's not visible on UI, you can add them explicitly. [!code highlight:5]
pages: [
{
path: '/docs/test',
},
],
},
}),
],
});
```
#### Waku [#waku]
Waku can serve your site statically when all pages are configured with `static` render mode.
See [Deployment](https://waku.gg/#deployment) for details.
{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.
### Middleware [#middleware-step]
Create a middleware that redirects users to appropriate locale.
```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).*)'],
};
```
The default middleware is optional, you can also use your own middleware or the one provided by i18n libraries.
Make sure its behaviour aligns with the [`hidePrefix`](/docs/headless/internationalization/config#hide-locale-prefix) option you set in your i18n config.
### Translations [#translations-step]
Define your translations in a file (e.g. `lib/layout.shared.tsx`), the English translations are used when `translations` is not specified.
You can also add `locale` parameter to `baseOptions()` for localized layout options:
```tsx title="lib/layout.shared.tsx"
import { i18n } from '@/lib/i18n';
import { defineI18nUI } from 'fumadocs-ui/i18n';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
// [!code ++:9]
export const i18nUI = defineI18nUI(i18n, {
en: {
displayName: 'English',
},
cn: {
displayName: 'Chinese',
search: '搜尋文檔',
},
});
// [!code highlight]
export function baseOptions(locale: string): BaseLayoutProps {
return {
// different props based on `locale`
};
}
```
Pass translations to `
{children}
);
}
```
### Routing [#routing-step]
Create a `/app/[lang]` folder, and move your pages/layouts into it, except route handlers.
Did you accidentally find your styles lost? Make sure the import path to `global.css` is still
correct!
### Pass Locale [#pass-locale-step]
Pass the locale to Fumadocs in your pages and layouts.
lib/source.ts
Home Layout
Docs Layout
Docs Page
```ts
import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';
export const source = loader({
i18n, // [!code ++]
// other options
});
```
```tsx title="app/[lang]/(home)/layout.tsx"
import type { ReactNode } from 'react';
import { HomeLayout } from 'fumadocs-ui/layouts/home';
import { baseOptions } from '@/lib/layout.shared';
export default async function Layout({
params,
children,
}: {
params: Promise<{ lang: string }>;
children: ReactNode;
}) {
const { lang } = await params;
return {children} ; // [!code highlight]
}
```
```tsx title="app/[lang]/docs/layout.tsx"
import type { ReactNode } from 'react';
import { source } from '@/lib/source';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/lib/layout.shared';
export default async function Layout({
params,
children,
}: {
params: Promise<{ lang: string }>;
children: ReactNode;
}) {
const { lang } = await params;
return (
// [!code highlight]
{children}
);
}
```
```ts title="app/[lang]/docs/[[...slug]]/page.tsx"
import { source } from '@/lib/source';
export default async function Page({
params,
}: {
params: Promise<{ lang: string; slug?: string[] }>;
}) {
const { slug, lang } = await params;
// get page
source.getPage(slug); // [!code --]
source.getPage(slug, lang); // [!code ++]
// get pages
source.getPages(); // [!code --]
source.getPages(lang); // [!code ++]
}
```
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
}
```
### Search [#search-step]
Configure i18n on your search solution.
* **Built-in Search (Orama):** See [Internationalization](/docs/headless/search/orama#internationalization).
* **Cloud Solutions (e.g. Algolia):** They usually have official support for multilingual.
### Installation [#installation]
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 { defineDocs, defineConfig } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
export default defineConfig();
```
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({
// customise the config file path
// configPath: "source.config.ts"
});
// [!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.
Setup an import alias (recommended):
```json title="tsconfig.json"
{
"compilerOptions": {
"paths": {
// [!code ++]
"collections/*": ["./.source/*"]
}
}
}
```
### Integrate with Fumadocs [#integrate-with-fumadocs]
You can create a `lib/source.ts` file and obtain Fumadocs source from the `docs` collection output.
```ts title="lib/source.ts"
import { docs } from 'collections/server';
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
The `.source` folder will be generated when you run `next dev` or `next build`.
### 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]
```
````
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]
```
#### Installation [#installation-step]
#### Write Code [#write-code-step]
#### Deploy [#deploy-step]
{
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
pnpm
yarn
bun
```bash
npm install beautiful-mermaid
```
```bash
pnpm add beautiful-mermaid
```
```bash
yarn add beautiful-mermaid
```
```bash
bun add 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.
Fumadocs MDX
```tsx 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.
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 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 title="Test" lineNumbers
type Player = {
/**
* The player name
* ```php
* $a = "60"
* ```
*
* @default 'user'
*/
name: string;
};
// ---cut---
// @noErrors
console.g;
// ^|
const player: Player = { name: 'Hello World' };
// ^?
````
```ts twoslash
const a = '123';
console.log(a);
// ^^^
```
```ts twoslash
// @errors: 2588
const a = '123';
a = 132;
```
# 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]
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 { useDocsSearch } from 'fumadocs-core/search/client';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
const appId = 'replace me';
const apiKey = 'replace me';
const client = liteClient(appId, apiKey);
export default function CustomSearchDialog(props: SharedProps) {
const { locale } = useI18n(); // (optional) for i18n
const { search, setSearch, query } = useDocsSearch({
type: 'algolia',
client,
indexName: 'document',
locale,
});
return (
Search powered by Algolia
);
}
```
`useDocsSearch()` 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:
provider.tsx
app/layout.tsx
```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
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 { 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 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, create a function to generate records.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import type { StructuredData } from 'fumadocs-core/mdx-plugins';
export interface DocumentRecord {
title: string;
description?: string;
url: string;
structured: StructuredData;
}
export async function exportSearchIndexes() {
const results: DocumentRecord[] = [];
for (const page of source.getPages()) {
results.push({
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return results;
}
```
Export it via static route handler.
Next.js
React Router
Tanstack Start
Waku
```ts title="app/static.json/route.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const revalidate = false;
export async function GET() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes/static.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function loader() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes.ts"
import { route, type RouteConfig } from '@react-router/dev/routes';
export default [
// [!code ++]
route('static.json', 'routes/static.ts'),
] satisfies RouteConfig;
```
```ts title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await exportSearchIndexes()),
},
},
});
```
```ts 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 static file
pages: [{ path: '/static.json' }],
}),
],
});
```
```ts title="pages/_api/static.json.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function GET() {
return Response.json(await exportSearchIndexes());
}
export const getConfig = () => ({
render: 'static',
});
```
Finally, the exported records can be accessed at:
Next.js
Tanstack Start
React Router
Waku
```ts
const filePath = '.next/server/app/static.json.body';
```
```ts
const filePath = '.output/public/static.json';
```
```ts
const filePath = 'build/client/static.json';
```
```ts
const filePath = 'dist/public/static.json';
```
You can read it for further processing:
```ts
import * as fs from 'node:fs';
import type { DocumentRecord } from '@/lib/export-search-indexes';
const content = fs.readFileSync(filePath);
const records = JSON.parse(content.toString()) as DocumentRecord[];
```
Use `structuredData` 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 { 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/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 { useDocsSearch } from 'fumadocs-core/search/client';
import { flexsearchStaticClient } 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, setSearch, query } = useDocsSearch({
client: flexsearchStaticClient({ 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:
provider.tsx
app/layout.tsx
```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
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 { useDocsSearch } from 'fumadocs-core/search/client';
import { flexsearchStaticClient } from 'fumadocs-core/search/client/flexsearch-static';
export default function CustomSearchDialog(props: SharedProps) {
// [!code ++]
const [tag, setTag] = useState();
const { search, setSearch, query } = useDocsSearch({
client: flexsearchStaticClient({
// [!code ++]
tag,
}),
});
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 customise the UI of document search.
## Search Client [#search-client]
You can choose & configure the search client according to your search engine, it defaults to Orama search.
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:
provider.tsx
app/layout.tsx
```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
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 { 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 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]
. 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 { OramaCloud } from '@orama/core';
import { useI18n } from 'fumadocs-ui/contexts/i18n';
const client = new OramaCloud({
projectId: '',
apiKey: '',
});
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-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:
provider.tsx
app/layout.tsx
```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
import { Provider } from './provider';
import type { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return (
{/* [!code --] */}
{children}
{/* [!code ++] */}
{children}
);
}
```
# Fumadocs (Framework Mode): Orama (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 Orama.
## Overview [#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 [#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-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:
provider.tsx
app/layout.tsx
```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
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 { 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 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]
. Integrate [Typesense Search](/docs/headless/search/typesense).
. 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: `YOUR_TYPESENSE_COLLECTION_NAME`,
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:
provider.tsx
app/layout.tsx
```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
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 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.
(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
pnpm
yarn
bun
```bash
npm i @content-collections/mdx
```
```bash
pnpm add @content-collections/mdx
```
```bash
yarn add @content-collections/mdx
```
```bash
bun add @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 {
frontmatterSchema,
metaSchema,
transformMDX,
} from '@fumadocs/content-collections/configuration';
const docs = defineCollection({
name: 'docs',
directory: 'content/docs',
include: '**/*.mdx',
schema: frontmatterSchema,
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 customise 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): 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) |
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.
### Fallback Language [#fallback-language]
The fallback language to use when translations are missing for a page, default to your `defaultLanguage`.
Supported:
* A language in your `languages` array.
* When set to `null`, no fallback will be used.
```ts
import { defineI18n } from 'fumadocs-core/i18n';
export const i18n = defineI18n({
languages: ['en', 'cn'],
defaultLanguage: 'en',
fallbackLanguage: 'cn',
});
```
# 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 customised 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 customise the heading id with `[#slug]`.
```md
# heading [#slug]
```
### Output [#output]
An array of `TOCItemType`.
For Fumadocs MDX, it is now enabled by default.
You can use the [`remarkNpm`](/docs/headless/mdx/remark-npm) plugin instead.
## Usage [#usage]
npm
pnpm
yarn
bun
```bash
npm install fumadocs-docgen
```
```bash
pnpm add fumadocs-docgen
```
```bash
yarn add fumadocs-docgen
```
```bash
bun add fumadocs-docgen
```
Add the remark plugin.
Fumadocs MDX
MDX Compiler
```ts title="source.config.ts"
import { remarkInstall } from 'fumadocs-docgen';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkInstall],
},
});
```
```ts
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
...
...
...
...
```
npm
pnpm
yarn
bun
```bash
npm install my-package
```
```bash
pnpm add my-package
```
```bash
yarn add my-package
```
```bash
bun add my-package
```
## Options [#options]
### Persistent [#persistent]
When using with Fumadocs UI, you can enable persistence with the `persist` option.
Fumadocs MDX
MDX Compiler
```ts title="source.config.ts"
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
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:
Input
Output
````md
```ts
console.log('Hello World');
```
````
```html
## Usage [#usage]
Add the rehype plugin.
MDX Compiler
Fumadocs MDX
```ts
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
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.
Input
Output
````mdx
```js title="Title"
console.log('Hello');
```
````
```jsx
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`.
Input
Output
````md
```ts
console.log('This should shows the logo of TypeScript');
```
````
```jsx
Disable or customise 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
pnpm
yarn
bun
```bash
npm i remark-directive
```
```bash
pnpm add remark-directive
```
```bash
yarn add remark-directive
```
```bash
bun add remark-directive
```
Configure both plugins in your config.
Fumadocs MDX
MDX Compiler
```ts title="source.config.ts"
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
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]
Input
Output
```md
:::tip[This is a `title`]
Hello World
:::
:::warning
Hello World
:::
```
```mdx
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 title="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkImage } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [remarkImage],
});
```
> This plugin is included by default on Fumadocs MDX.
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]
```
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
import { remarkImage } from 'fumadocs-core/mdx-plugins';
export default {
remarkPlugins: [[remarkImage, { 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]
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 (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
Generate markdown for LLM consumption with customizable placeholders
The `remarkLLMs` plugin stringifies the processed Markdown AST to plain Markdown, the output is generated as an ESM export. This is useful for feeding content to LLMs, search indexing, or other text-based processing.
## Usage [#usage]
### Fumadocs MDX [#fumadocs-mdx]
Enable `includeProcessedMarkdown` in your collection config, Fumadocs MDX runs `remarkLLMs` internally when this is set.
```ts title="source.config.ts"
import { defineDocs } from 'fumadocs-mdx/config';
import { type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
// options...
};
export default defineDocs({
docs: {
postprocess: {
includeProcessedMarkdown: llmsOptions,
},
},
});
```
The stringified Markdown is exported as `_markdown` and available via `getText('processed')`, see [Collections](/docs/mdx/collections#includeprocessedmarkdown) for details.
### MDX Compiler [#mdx-compiler]
When using the MDX Compiler (or a custom pipeline), add the plugin:
```ts
import { compile } from '@mdx-js/mdx';
import { remarkLLMs, type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
// The output will be exported as `_markdown`
as: '_markdown',
};
const vfile = await compile('...', {
remarkPlugins: [[remarkLLMs, llmsOptions]],
});
```
## Placeholders [#placeholders]
Placeholders let you keep certain MDX components in the stringified output as special tokens instead of dropping or inlining them. That way you can:
. Rehydrate those tokens later via `renderPlaceholder()`.
. Generate a better Markdown representation with runtime data.
### Using `mdxAsPlaceholder` [#using-mdxasplaceholder]
List component names to treat as placeholders:
```ts
import { type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
// [!code ++]
mdxAsPlaceholder: ['Callout', 'Card'],
};
```
In the exported Markdown, `` and `` will appear as placeholder tokens, like:
```
\0{"name": "Callout", ...}\0
```
### Using `stringify` [#using-stringify]
For full control, use the `stringify` option and with the `placeholder()` helper:
```ts
import { placeholder, type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
stringify(node, parent, state, info) {
if (node.type === 'mdxJsxFlowElement' && node.name === 'MyPage') {
return placeholder(node, parent, state, info);
}
},
};
```
### Rendering Placeholders [#rendering-placeholders]
Use `renderPlaceholder()` from the runtime module to replace placeholder tokens with custom output:
```ts
import { renderPlaceholder } from 'fumadocs-core/mdx-plugins/remark-llms.runtime';
const markdown = await getExportedMarkdown(); // e.g. from _markdown
const rendered = await renderPlaceholder(markdown, {
async Callout({ name, attributes, children }) {
// note: you can also fetch data here
const data = await fetchData();
return `[${attributes.type ?? 'info'}] ${children}`;
},
Card({ attributes, children }) {
return `**${attributes.title}**\n\n${children}`;
},
});
```
Each renderer receives `PlaceholderData`:
* `name`
* `attributes`
* `children` (the stringified child content).
## Example [#example]
Input
Output
```mdx
# Getting started
Hello **world**.
Some paragraph.
```
```md
# Getting started [#getting-started]
\0{"name":"Callout","attributes":{"type":"tip"},"children":"Hello **world**."}\0
Some paragraph.
```
## Options [#options]
```
## Setup [#setup]
Add the remark plugin:
Fumadocs MDX
MDX Compiler
```tsx title="source.config.ts"
import { remarkMdxFiles } from 'fumadocs-core/mdx-plugins';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkMdxFiles],
},
});
```
```ts
import { compile } from '@mdx-js/mdx';
import { remarkMdxFiles } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [remarkMdxFiles],
});
```
And make sure you have defined `
MDX Compiler
Fumadocs MDX
```ts
import { compile } from '@mdx-js/mdx';
import { remarkNpm } from 'fumadocs-core/mdx-plugins';
await compile('...', {
remarkPlugins: [remarkNpm],
});
```
```ts title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkNpmOptions: {
// it is enabled by default, customise it here
},
},
});
```
Define the required components:
Custom
Fumadocs UI
```tsx title="components/mdx.tsx"
import { CodeBlockTabs, CodeBlockTab, CodeBlockTabsList, CodeBlockTabsTrigger } from 'my-ui';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
CodeBlockTabs,
CodeBlockTab,
CodeBlockTabsList,
CodeBlockTabsTrigger,
...components,
} satisfies MDXComponents;
}
```
```tsx title="components/mdx.tsx"
import defaultComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
// it's included by default in `defaultComponents`
...defaultComponents,
...components,
} satisfies MDXComponents;
}
```
| Component | |
| -------------------- | ----------------------------------------------- |
| CodeBlockTabs | Accepts a `defaultValue` prop for default value |
| CodeBlockTabsList | N/A |
| CodeBlockTab | Accepts a `value` prop |
| CodeBlockTabsTrigger | Accepts a `value` prop |
### Input [#input]
Create code blocks with `npm` as language.
````mdx
```npm
npm i my-package
```
```npm
npm i my-package -D
```
````
### Output [#output]
The following structure should be generated by the plugin.
```mdx
npm
pnpm
yarn
bun
...
...
...
...
```
npm
pnpm
yarn
bun
```bash
npm i my-package
```
```bash
pnpm add my-package
```
```bash
yarn add my-package
```
```bash
bun add my-package
```
### Persistent [#persistent]
When using with Fumadocs UI, you can enable persist the selected value with the `persist` option.
Fumadocs MDX
MDX Compiler
```ts title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkNpmOptions: {
persist: {
id: 'package-manager',
},
},
},
});
```
```ts
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 `
MDX Compiler
Fumadocs MDX
```ts
import { compile } from '@mdx-js/mdx';
import { remarkSteps } from 'fumadocs-core/mdx-plugins/remark-steps';
await compile('...', {
remarkPlugins: [remarkSteps],
});
```
```ts title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
import { remarkSteps } from 'fumadocs-core/mdx-plugins/remark-steps';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkSteps],
},
});
```
### Input [#input]
Create step headings:
Using Tag
Using Number
```md
# Heading 1 [step]
## Sub Heading 1 [step]
## Sub Heading 2 [step]
# Heading 2 [step]
```
```md
# 1. Heading 1
## 1. Sub Heading 1
## 2. Sub Heading 2
# 2. Heading 2
```
### Output [#output]
The following structure should be generated by the plugin.
```mdx
```
# Fumadocs Core (the core library of Fumadocs): Remark TS to JS
URL: /docs/headless/mdx/remark-ts2js
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-ts2js.mdx
A remark plugin to transform TypeScript codeblocks into two tabs of codeblock with its JavaScript variant.
## Usage [#usage]
Install dependencies:
npm
pnpm
yarn
bun
```bash
npm i fumadocs-docgen oxc-transform
```
```bash
pnpm add fumadocs-docgen oxc-transform
```
```bash
yarn add fumadocs-docgen oxc-transform
```
```bash
bun add fumadocs-docgen oxc-transform
```
For Next.js, externalize `oxc-transform`:
```js title="next.config.mjs (Next.js)"
import { createMDX } from 'fumadocs-mdx/next';
/** @type {import('next').NextConfig} */
const config = {
reactStrictMode: true,
serverExternalPackages: ['oxc-transform'],
};
const withMDX = createMDX();
export default withMDX(config);
```
Add the remark plugin:
Fumadocs MDX
MDX Compiler
```ts title="source.config.ts"
import { remarkTypeScriptToJavaScript } from 'fumadocs-docgen/remark-ts2js';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkTypeScriptToJavaScript],
},
});
```
```ts
import { remarkTypeScriptToJavaScript } from 'fumadocs-docgen/remark-ts2js';
import { compile } from '@mdx-js/mdx';
await compile('...', {
remarkPlugins: [remarkTypeScriptToJavaScript],
});
```
Finally, make sure to define the required MDX components: `Tabs` and `Tab`.
```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;
}
```
You can now enable it on TypeScript/TSX codeblocks, like:
````md
```tsx ts2js
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return
TypeScript
JavaScript
```tsx
import { ReactNode } from 'react';
export default function Layout({ children }: { children: ReactNode }) {
return
```jsx
export default function Layout({ children }) {
return
# 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 information from your documents, useful for implementing document search
## Usage [#usage]
Add it as a remark plugin.
MDX Compiler
Fumadocs MDX
```ts
import { compile } from '@mdx-js/mdx';
import { remarkStructure } from 'fumadocs-core/mdx-plugins';
const vfile = await compile('...', {
remarkPlugins: [remarkStructure],
});
```
```ts title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
// This plugin is enabled by default on Fumadocs MDX
// options:
remarkStructureOptions: {},
},
});
```
Extracted information could be found in `vfile.data.structuredData`, you may
write your own plugin to convert it into a MDX export.
### Options [#options]
A heading can have multiple paragraphs.
#### Heading [#heading]
| Prop | |
| --------- | ------------------------------------ |
| `id` | unique identifier or slug of heading |
| `content` | Text content (Markdown) |
#### Content [#content]
| Prop | |
| --------- | ------------------------------- |
| `heading` | Heading of paragraph (nullable) |
| `content` | Text content (Markdown) |
The content is stringified as Markdown text, you can customise it using the [`stringify`](#options) option.
## As a Function [#as-a-function]
Accepts MDX/markdown content and return structurized data.
```ts
import { structure } from 'fumadocs-core/mdx-plugins';
structure(page.body.raw);
```
If you have custom remark plugins enabled, such as
`remark-math`, you have to pass these plugins to the function. This avoids unreadable content on paragraphs.
```ts
import { structure } from 'fumadocs-core/mdx-plugins';
import remarkMath from 'remark-math';
structure(page.body.raw, [remarkMath]);
```
### Parameters [#parameters]
| Parameter | |
| --------------- | ---------------------- |
| `content` | MDX/markdown content |
| `remarkPlugins` | List of remark plugins |
| `options` | Custom options |
# 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:
npm
pnpm
yarn
bun
```bash
npm install algoliasearch
```
```bash
pnpm add algoliasearch
```
```bash
yarn add algoliasearch
```
```bash
bun add algoliasearch
```
### Sign up on Algolia [#sign-up-on-algolia]
Sign up and obtain the app id and API keys for your search. Store these
credentials in environment variables.
### Sync Search Indexes [#sync-search-indexes]
Pre-render a static route `/static.json` to export search indexes into production build:
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import type { DocumentRecord } from 'fumadocs-core/search/algolia';
export async function exportSearchIndexes() {
const results: DocumentRecord[] = [];
for (const page of source.getPages()) {
results.push({
_id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return results;
}
```
Next.js
React Router
Tanstack Start
Waku
```ts title="app/static.json/route.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const revalidate = false;
export async function GET() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes/static.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function loader() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes.ts"
import { route, type RouteConfig } from '@react-router/dev/routes';
export default [
// [!code ++]
route('static.json', 'routes/static.ts'),
] satisfies RouteConfig;
```
```ts title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await exportSearchIndexes()),
},
},
});
```
```ts 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 static file
pages: [{ path: '/static.json' }],
}),
],
});
```
```ts title="pages/_api/static.json.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function GET() {
return Response.json(await exportSearchIndexes());
}
export const getConfig = () => ({
render: 'static',
});
```
Make a script to sync search indexes:
```ts title="scripts/sync-content.ts" twoslash
import { algoliasearch } from 'algoliasearch';
import { sync, DocumentRecord } from 'fumadocs-core/search/algolia';
import * as fs from 'node:fs';
const filePath = '';
const content = fs.readFileSync(filePath);
const records = JSON.parse(content.toString()) as DocumentRecord[];
const client = algoliasearch('id', 'key');
// update the index settings and sync search indexes
void sync(client, {
indexName: 'document',
documents: records,
});
```
`filePath` refers to the path of pre-rendered `static.json`, choose one according to your setup:
Next.js
Tanstack Start
React Router
Waku
```ts
const filePath = '.next/server/app/static.json.body';
```
```ts
const filePath = '.output/public/static.json';
```
```ts
const filePath = 'build/client/static.json';
```
```ts
const filePath = 'dist/public/static.json';
```
Now run the script after build:
```json title="package.json"
{
"scripts": {
"build": "... && bun ./scripts/sync-content.ts"
}
}
```
### Workflow [#workflow]
You may manually upload search indexes with the script, or integrate it with your CI/CD pipeline.
### 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 { useDocsSearch } from 'fumadocs-core/search/client';
const client = liteClient('id', 'key');
const { search, setSearch, query } = useDocsSearch({
type: 'algolia',
indexName: 'document',
client,
});
```
* Use their official clients directly.
## Advanced [#advanced]
### Tag Filter [#tag-filter]
To configure tag filtering, add a `tag` value to indexes.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import type { DocumentRecord } from 'fumadocs-core/search/algolia';
export async function exportSearchIndexes() {
const results: DocumentRecord[] = [];
for (const page of source.getPages()) {
results.push({
_id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
// [!code ++]
tag: '',
});
}
return results;
}
```
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 { useDocsSearch } from 'fumadocs-core/search/client';
const { search, setSearch, query } = useDocsSearch({
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
pnpm
yarn
bun
```bash
npm install flexsearch
```
```bash
pnpm add flexsearch
```
```bash
yarn add flexsearch
```
```bash
bun add flexsearch
```
npm
pnpm
yarn
bun
```bash
npm install @types/flexsearch -D
```
```bash
pnpm add @types/flexsearch -D
```
```bash
yarn add @types/flexsearch --dev
```
```bash
bun add @types/flexsearch --dev
```
### 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 { useDocsSearch } from 'fumadocs-core/search/client';
const client = useDocsSearch({
type: 'fetch',
});
```
',
};
},
});
```
and update your search client:
* **Fumadocs UI**: Configure [Tag Filter](/docs/search/flexsearch#tag-filter) on Search UI.
* **Search Client**: pass a tag to the hook.
```ts
import { useDocsSearch } from 'fumadocs-core/search/client';
const client = useDocsSearch({
type: 'fetch',
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 { useDocsSearch } from 'fumadocs-core/search/client';
import { flexsearchStaticClient } from 'fumadocs-core/search/client/flexsearch-static';
const client = useDocsSearch({
client: flexsearchStaticClient({
// optional: pass tag & locale
tag,
}),
});
```
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.
From Source
From Search Indexes
```ts title="app/api/search/route.ts"
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
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): 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
## Introduction [#introduction]
The Mixedbread Integration uses vector search to provide semantic search capabilities for your documentation. It indexes your documentation content into a store, enabling users to search using natural language queries and find relevant content based on meaning rather than just keyword matching.
## Setup [#setup]
### Get your API Key [#get-your-api-key]
. Sign up at [Mixedbread](https://platform.mixedbread.com)
. Navigate to [API Keys](https://platform.mixedbread.com/platform?next=api-keys)
. Create a new API key and store it in your environment variables
### Create a Store [#create-a-store]
To sync your documentation, you'll need to create a store:
. Go to the [Stores](https://platform.mixedbread.com/platform?next=stores) in your Mixedbread dashboard
. Create a new store for your documentation
. Copy the store ID
### Sync Documentation [#sync-documentation]
Use the [Mixedbread CLI](https://www.mixedbread.com/cli) to sync your documentation:
Install the CLI:
npm
pnpm
yarn
bun
```bash
npm install @mixedbread/cli -D
```
```bash
pnpm add @mixedbread/cli -D
```
```bash
yarn add @mixedbread/cli --dev
```
```bash
bun add @mixedbread/cli --dev
```
Configure authentication and sync your documentation:
```bash
# Configure authentication
mxbai config keys add YOUR_API_KEY
# Sync your documentation
mxbai vs sync YOUR_STORE_ID "./content/docs"
```
The CLI will automatically detect changes in your documentation and update the store accordingly.
### Workflow [#workflow]
You can automatically sync your documentation by adding a sync script to your `package.json`:
```json
{
"scripts": {
"build": "... && mxbai vs sync YOUR_STORE_ID './content/docs' --ci"
}
}
```
### Search API [#search-api]
Create an API route to handle search requests server-side:
```ts title="app/api/search/route.ts"
import { createMixedbreadSearchAPI } from 'fumadocs-core/search/mixedbread';
import Mixedbread from '@mixedbread/sdk';
const client = new Mixedbread({
apiKey: 'YOUR_API_KEY',
});
export const { GET } = createMixedbreadSearchAPI({
client,
storeIdentifier: 'YOUR_STORE_ID',
});
```
### Search Client [#search-client]
* **Fumadocs UI**: see [Search UI](/docs/search/mixedbread) for details.
* **Search Client**:
```ts
import { useDocsSearch } from 'fumadocs-core/search/client';
const client = useDocsSearch({
type: 'fetch',
api: '/api/search',
});
```
## Options [#options]
### Tag Filter [#tag-filter]
To filter search results by tags, add a tag field to your document metadata:
```md
---
title: Mixedbread
description: Integrate Mixedbread Search with Fumadocs
url: /docs/headless/search/mixedbread
// [!code ++]
tag: docs
---
```
And update your search client:
* **Fumadocs UI**: Enable [Tag Filter](/docs/search/mixedbread#tag-filter) on Search UI.
* **Search Client**: You can add the tag filter like:
```ts
import { useDocsSearch } from 'fumadocs-core/search/client';
const { search, setSearch, query } = useDocsSearch({
type: 'fetch',
api: '/api/search',
tag: '',
// ...
});
```
This allows you to scope searches to specific sections of your documentation.
# 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.
. Create a new project with **REST API** data source on Orama Cloud dashboard.
Store your credentials in environment variables, for example:
```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"
```
. Export the search indexes by pre-rendering a static route.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import type { OramaDocument } from 'fumadocs-core/search/orama-cloud';
export async function exportSearchIndexes() {
return source.getPages().map((page) => {
return {
id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
} satisfies OramaDocument;
});
}
```
Next.js
React Router
Tanstack Start
Waku
```ts title="app/static.json/route.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const revalidate = false;
export async function GET() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes/static.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function loader() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes.ts"
import { route, type RouteConfig } from '@react-router/dev/routes';
export default [
// [!code ++]
route('static.json', 'routes/static.ts'),
] satisfies RouteConfig;
```
```ts title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await exportSearchIndexes()),
},
},
});
```
```ts 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 static file
pages: [{ path: '/static.json' }],
}),
],
});
```
```ts title="pages/_api/static.json.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function GET() {
return Response.json(await exportSearchIndexes());
}
export const getConfig = () => ({
render: 'static',
});
```
. Create a script to sync search indexes.
```ts title="scripts/sync-content.ts"
import { sync, type OramaDocument } from 'fumadocs-core/search/orama-cloud';
import * as fs from 'node:fs/promises';
import { OramaCloud } from '@orama/core';
const filePath = '';
async function main() {
const orama = new OramaCloud({
projectId: process.env.NEXT_PUBLIC_ORAMA_PROJECT_ID,
apiKey: process.env.ORAMA_PRIVATE_API_KEY,
});
const content = await fs.readFile(filePath);
const records = JSON.parse(content.toString()) as OramaDocument[];
await sync(orama, {
index: process.env.NEXT_PUBLIC_ORAMA_DATASOURCE_ID,
documents: records,
});
console.log(`search updated: ${records.length} records`);
}
void main();
```
`filePath` refers to the path of pre-rendered `static.json`, choose one according to your setup:
Next.js
Tanstack Start
React Router
Waku
```ts
const filePath = '.next/server/app/static.json.body';
```
```ts
const filePath = '.output/public/static.json';
```
```ts
const filePath = 'build/client/static.json';
```
```ts
const filePath = 'dist/public/static.json';
```
. Run the script after production build, make sure the environment variables are available (e.g. Bun reads from `.env` files):
```json title="package.json"
{
"scripts": {
"build": "... && bun scripts/sync-content.ts"
}
}
```
### 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 { useDocsSearch } from 'fumadocs-core/search/client';
import { OramaCloud } from '@orama/core';
const client = new OramaCloud({
projectId: process.env.NEXT_PUBLIC_ORAMA_PROJECT_ID,
apiKey: process.env.NEXT_PUBLIC_ORAMA_API_KEY,
});
const { search, setSearch, query } = useDocsSearch({
type: 'orama-cloud',
client,
params: {
// optional search params
},
});
```
* Use their search client directly.
## Web Crawler [#web-crawler]
. Create a Crawler data source from dashboard, and configure it correctly with the "Documentation" preset.
. 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 { useDocsSearch } from 'fumadocs-core/search/client';
import { OramaCloud } from '@orama/core';
const client = new OramaCloud({
projectId: '',
apiKey: '',
});
const { search, setSearch, query } = useDocsSearch({
type: 'orama-cloud',
index: 'crawler',
client,
params: {
// optional search 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 Orama, 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.
Next.js
React Router
Tanstack Start
Waku
```ts title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
export const { GET } = createFromSource(source, {
// https://docs.orama.com/docs/orama-js/supported-languages
language: 'english',
});
```
```ts 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, {
// https://docs.orama.com/docs/orama-js/supported-languages
language: 'english',
});
export async function loader({ request }: Route.LoaderArgs) {
return server.GET(request);
}
```
```ts 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, {
// https://docs.orama.com/docs/orama-js/supported-languages
language: 'english',
});
export const Route = createFileRoute('/api/search')({
server: {
handlers: {
GET: async ({ request }) => server.GET(request),
},
},
});
```
```ts title="src/pages/_api/api/search.ts"
import { createFromSource } from 'fumadocs-core/search/server';
import { source } from '@/lib/source';
export const { GET } = createFromSource(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.
Next.js
React Router
Tanstack Start
Waku
```ts title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';
export const { GET } = createSearchAPI('advanced', {
language: 'english',
indexes: source.getPages().map((page) => ({
title: page.data.title,
description: page.data.description,
url: page.url,
id: page.url,
structuredData: page.data.structuredData,
})),
});
```
```ts 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', {
language: 'english',
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 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', {
language: 'english',
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 title="src/pages/_api/api/search.ts"
import { source } from '@/lib/source';
import { createSearchAPI } from 'fumadocs-core/search/server';
export const { GET } = createSearchAPI('advanced', {
language: 'english',
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/orama) for details.
* **Search Client**:
```ts twoslash
import { useDocsSearch } from 'fumadocs-core/search/client';
const client = useDocsSearch({
type: 'fetch',
});
```
',
};
},
});
```
and update your search client:
* **Fumadocs UI**: Configure [Tag Filter](/docs/search/orama#tag-filter) on Search UI.
* **Search Client**: pass a tag to the hook.
```ts
import { useDocsSearch } from 'fumadocs-core/search/client';
const client = useDocsSearch({
type: 'fetch',
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.
Next.js
React Router
Tanstack Start
Waku
```ts 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 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 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 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 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',
});
```
> `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 `static` instead of `fetch`.
```ts
import { useDocsSearch } from 'fumadocs-core/search/client';
const client = useDocsSearch({
type: 'static',
});
```
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]
Make sure your language is on the Orama [Supported Languages](https://docs.orama.com/docs/orama-js/supported-languages) list.
From Source
From Search Indexes
```ts title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
const server = createFromSource(source, {
localeMap: {
// [locale]: Orama options [!code ++:2]
ru: { language: 'russian' },
en: { language: 'english' },
},
});
```
```ts
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 === 'ru' ? 'russian' : 'english', // [!code ++]
})),
),
});
```
For **Static Mode**, you should configure from client-side instead:
```tsx title="components/search.tsx"
import { useDocsSearch } from 'fumadocs-core/search/client';
import { create } from '@orama/orama';
function initOrama(locale?: string) {
return create({
schema: { _: 'string' },
// [!code ++]
language: locale === 'ru' ? 'russian' : 'english',
});
}
function Search() {
const client = useDocsSearch({
type: 'static',
initOrama,
});
// ...
}
```
### Special Languages [#special-languages]
Chinese and Japanese require additional configurations:
npm
pnpm
yarn
bun
```bash
npm i @orama/tokenizers
```
```bash
pnpm add @orama/tokenizers
```
```bash
yarn add @orama/tokenizers
```
```bash
bun add @orama/tokenizers
```
createFromSource
Static mode
```ts title="app/api/search/route.ts"
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';
import { createTokenizer } from '@orama/tokenizers/mandarin';
export const { GET } = createFromSource(source, {
localeMap: {
// [locale]: Orama options
cn: {
components: {
tokenizer: createTokenizer(),
},
search: {
threshold: 0,
tolerance: 0,
},
},
},
});
```
```tsx title="components/search.tsx"
import { useDocsSearch } from 'fumadocs-core/search/client';
import { createTokenizer } from '@orama/tokenizers/mandarin';
import { create } from '@orama/orama';
// [!code focus:8]
function initOrama(locale?: string) {
return create({
schema: { _: 'string' },
components: {
tokenizer: locale === 'cn' ? createTokenizer() : undefined,
},
});
}
function Search() {
const client = useDocsSearch({
type: 'static',
initOrama,
});
// ...
}
```
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 { useDocsSearch } from 'fumadocs-core/search/client';
const { search, setSearch, query } = useDocsSearch({
type: 'fetch',
locale: 'cn',
});
```
## 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]
npm
pnpm
yarn
bun
```bash
npm install trieve-ts-sdk trieve-fumadocs-adapter
```
```bash
pnpm add trieve-ts-sdk trieve-fumadocs-adapter
```
```bash
yarn add trieve-ts-sdk trieve-fumadocs-adapter
```
```bash
bun add 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 these credentials in environment variables.
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]
Export the search indexes by pre-rendering a static route.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import { type TrieveDocument } from 'trieve-fumadocs-adapter/search/sync';
export async function exportSearchIndexes() {
const results: TrieveDocument[] = [];
for (const page of source.getPages()) {
results.push({
_id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
});
}
return results;
}
```
Next.js
React Router
Tanstack Start
Waku
```ts title="app/static.json/route.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const revalidate = false;
export async function GET() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes/static.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function loader() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes.ts"
import { route, type RouteConfig } from '@react-router/dev/routes';
export default [
// [!code ++]
route('static.json', 'routes/static.ts'),
] satisfies RouteConfig;
```
```ts title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await exportSearchIndexes()),
},
},
});
```
```ts 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 static file
pages: [{ path: '/static.json' }],
}),
],
});
```
```ts title="pages/_api/static.json.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function GET() {
return Response.json(await exportSearchIndexes());
}
export const getConfig = () => ({
render: 'static',
});
```
Create a script, the `sync` function will sync search indexes.
```ts title="scripts/sync-content.ts"
import * as fs from 'node:fs';
import { sync, type TrieveDocument } from 'trieve-fumadocs-adapter/search/sync';
import { TrieveSDK } from 'trieve-ts-sdk';
const filePath = '';
const content = fs.readFileSync(filePath);
const records: TrieveDocument[] = JSON.parse(content.toString());
const client = new TrieveSDK({
apiKey: 'adminApiKey',
datasetId: 'datasetId',
});
sync(client, records);
```
`filePath` refers to the path of pre-rendered `static.json`, choose one according to your setup:
Next.js
Tanstack Start
React Router
Waku
```ts
const filePath = '.next/server/app/static.json.body';
```
```ts
const filePath = '.output/public/static.json';
```
```ts
const filePath = 'build/client/static.json';
```
```ts
const filePath = 'dist/public/static.json';
```
Make sure to run the script after build:
```json title="package.json"
{
"scripts": {
"build": "... && bun scripts/sync-content.ts"
}
}
```
> You can also integrate it with your CI/CD pipeline.
### 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]
npm
pnpm
yarn
bun
```bash
npm install typesense typesense-fumadocs-adapter
```
```bash
pnpm add typesense typesense-fumadocs-adapter
```
```bash
yarn add typesense typesense-fumadocs-adapter
```
```bash
bun add 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 obtain the API key and server URL.
### Sync Dataset [#sync-dataset]
Export the search indexes by pre-rendering a static route.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import { findPath } from 'fumadocs-core/page-tree';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
export async function exportSearchIndexes() {
const results: DocumentRecord[] = [];
function isBreadcrumbItem(item: unknown): item is string {
return typeof item === 'string' && item.length > 0;
}
for (const page of source.getPages()) {
let breadcrumbs: string[] | undefined;
const pageTree = source.getPageTree(page.locale);
const path = findPath(
pageTree.children,
(node) => node.type === 'page' && node.url === page.url,
);
if (path) {
breadcrumbs = [];
path.pop();
if (isBreadcrumbItem(pageTree.name)) {
breadcrumbs.push(pageTree.name);
}
for (const segment of path) {
if (!isBreadcrumbItem(segment.name)) continue;
breadcrumbs.push(segment.name);
}
}
results.push({
_id: page.url,
structured: page.data.structuredData,
url: page.url,
title: page.data.title,
description: page.data.description,
breadcrumbs,
locale: page.locale,
});
}
return results;
}
```
Next.js
React Router
Tanstack Start
Waku
```ts title="app/static.json/route.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const revalidate = false;
export async function GET() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes/static.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function loader() {
return Response.json(await exportSearchIndexes());
}
```
```ts title="app/routes.ts"
import { route, type RouteConfig } from '@react-router/dev/routes';
export default [
// [!code ++]
route('static.json', 'routes/static.ts'),
] satisfies RouteConfig;
```
```ts title="src/routes/static[.]json.ts"
import { createFileRoute } from '@tanstack/react-router';
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export const Route = createFileRoute('/static.json')({
server: {
handlers: {
GET: async () => Response.json(await exportSearchIndexes()),
},
},
});
```
```ts 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 static file
pages: [{ path: '/static.json' }],
}),
],
});
```
```ts title="pages/_api/static.json.ts"
import { exportSearchIndexes } from '@/lib/export-search-indexes';
export async function GET() {
return Response.json(await exportSearchIndexes());
}
export const getConfig = () => ({
render: 'static',
});
```
Create a script to sync search indexes:
```ts title="scripts/sync-content.ts"
import * as fs from 'node:fs';
import { sync, DocumentRecord } from 'typesense-fumadocs-adapter';
import { Client } from 'typesense';
const filePath = '';
const content = fs.readFileSync(filePath);
const records = JSON.parse(content.toString()) as DocumentRecord[];
const client = new Client({
nodes: [{ url: 'YOUR_TYPESENSE_SERVER_URL' }],
apiKey: 'YOUR_TYPESENSE_API_KEY_WITH_WRITE_ACCESS',
connectionTimeoutSeconds: 60 * 15,
});
// update the collection settings and sync search indexes
void sync(client, {
typesenseCollectionName: 'YOUR_COLLECTION_NAME',
documents: records,
});
```
`filePath` refers to the path of pre-rendered `static.json`, choose one according to your setup:
Next.js
Tanstack Start
React Router
Waku
```ts
const filePath = '.next/server/app/static.json.body';
```
```ts
const filePath = '.output/public/static.json';
```
```ts
const filePath = 'build/client/static.json';
```
```ts
const filePath = 'dist/public/static.json';
```
Make sure to run the script after build:
```json title="package.json"
{
"scripts": {
"build": "... && bun scripts/sync-content.ts"
}
}
```
> You can also integrate it with your CI/CD pipeline.
### 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: 'YOUR_COLLECTION_NAME',
client,
});
```
## Options [#options]
### Tag Filter [#tag-filter]
To configure tag filtering, add a `tag` value to indexes.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
export async function exportSearchIndexes() {
const results: DocumentRecord[] = [];
for (const page of source.getPages()) {
results.push({
// other fields...
// [!code ++]
tag: '',
});
}
return results;
}
```
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]
To support internationalization, make sure to add a `locale` value to each document.
```ts title="lib/export-search-indexes.ts"
import { source } from '@/lib/source';
import { findPath } from 'fumadocs-core/page-tree';
import type { DocumentRecord } from 'typesense-fumadocs-adapter';
export async function exportSearchIndexes() {
const results: DocumentRecord[] = [];
for (const page of source.getPages()) {
results.push({
// other fields...
// [!code ++]
locale: page.locale,
});
}
return results;
}
```
And update your 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., `YOUR_COLLECTION_NAME_en`, `YOUR_COLLECTION_NAME_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 customise 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) {
console.log(file.path, file.data);
// 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]
The loader outputs a source object.
### 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.
Server
Client
```ts
import { source } from '@/lib/source';
// where you pass loader data
async function loader() {
const pageTree = source.getPageTree();
return {
pageTree: await source.serializePageTree(pageTree),
};
}
```
```tsx
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 ... ;
}
```
# 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 customise 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:
Strictly Typed
Simple
```ts
import { loader } from 'fumadocs-core/source';
export const source = loader({
plugins: ({ typedPlugin }) => [
typedPlugin({
// plugin config
}),
],
});
```
```ts
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 customise 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]
`loader()` accepts different content sources based on a `source` interface.
### Multiple Sources [#multiple-sources]
Use `multiple` to combine multiple sources into one.
```ts
import { loader, multiple } from 'fumadocs-core/source';
import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
import { blog, docs } from 'collections/server';
import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';
export const source = loader(
multiple({
docs: docs.toFumadocsSource(),
openapi: blog.toFumadocsSource(),
}),
{
baseUrl: '/docs',
},
);
```
To access properties exclusive to each source:
```ts
const page = source.getPage(['...']);
if (page.data.type === 'docs') {
console.log(page.data);
} else {
console.log(page.data);
}
```
### Custom Source [#custom-source]
To plug your own content source, create a `Source` 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 { Source } from 'fumadocs-core/source';
export function createMySource(): Source<{
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'],
// ...
},
},
],
};
}
```
# 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): 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
Tiny wrapper for negotiation features.
## Overview [#overview]
For React.js frameworks supporting middlewares, you can use the Negotiation API of Fumadocs for basic functionalities.
It is a tiny wrapper of `negotiator`.
### 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 customise 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:
Dynamic CodeBlock (UI)
Rehype Code (Core)
```tsx
'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
import { createRehypeCode } from 'fumadocs-core/mdx-plugins/rehype-code.core';
const rehypeCode = createRehypeCode(myShikiFactory);
```
# Fumadocs MDX (the built-in content source): Next.js
URL: /docs/mdx/next
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/(integrations)/next.mdx
Use Fumadocs MDX with Next.js
## Setup [#setup]
Set up Fumadocs MDX for your Next.js application.
## What is Next? [#what-is-next]
Learn how to access collection outputs.
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]
Learn how to access collection outputs.
Hit performance bottleneck? You can try lazy loading.
# Fumadocs MDX (the built-in content source): Browser Entry
URL: /docs/mdx/entry/browser
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/entry/browser.mdx
Access collections from browser/client environment.
## Usage [#usage]
The generated outputs are optimized using async imports to optimize for browser environments.
Only doc/docs collections are accessible on browser.
```tsx
import browserCollections from 'collections/browser';
// unloaded entries
console.log(browserCollections['collection name'].raw);
// define client-side collection loader
const clientLoader = browserCollections['collection name'].createClientLoader({
component(
// access the compiled file
{ default: MDX },
// define props (optional)
props: { myProp: string },
) {
return (
Docs (Meta + Doc)
Doc
```ts
// [!code highlight]
import { docs } from 'collections/dynamic';
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
```ts
// [!code highlight]
import { blogPosts } from 'collections/dynamic';
import { toFumadocsSource } from 'fumadocs-mdx/runtime/server';
import { loader } from 'fumadocs-core/source';
export const blog = loader({
baseUrl: '/blog',
source: toFumadocsSource(blogPosts, []),
});
```
# Fumadocs MDX (the built-in content source): Import MDX Files
URL: /docs/mdx/entry/import
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/entry/import.mdx
Importing MDX files directly.
## Introduction [#introduction]
MDX files will be compiled into JavaScript with exports like:
* `default`: the main component.
* `frontmatter`: frontmatter data.
* other properties generated by remark/rehype plugins.
Hence, they can also be used as a page, or components that you can import.
### Using as Component [#using-as-component]
You can import them as a component:
```tsx title="app/my-page.tsx"
import MyPage from '@/content/page.mdx';
import { getMDXComponents } from '@/components/mdx';
export default function Page() {
return (
app/my-page/page.mdx
components/layouts/page.tsx
```mdx
---
title: My Page
---
export { default } from '@/components/layouts/page';
# Hello World
This is my page.
```
```tsx
import type { ComponentProps } from 'react';
export default function Content(props: ComponentProps<'main'>) {
return (
{props.children}
);
}
```
It doesn't have **MDX components** by default, you have to provide them:
components/mdx.tsx
source.config.ts
```tsx
import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultMdxComponents, // for Fumadocs UI
...components,
} satisfies MDXComponents;
}
// export a `useMDXComponents()` that returns MDX components
export const useMDXComponents = getMDXComponents; // [!code ++]
```
```ts
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
// Path to import your `components/mdx.tsx` above. [!code ++]
providerImportSource: '@/components/mdx',
},
});
```
Other React.js frameworks like Tanstack Start usually prefer explicit declaration of loaders, it's recommended to use them as components in your pages instead.
# Fumadocs MDX (the built-in content source): Accessing Collections
URL: /docs/mdx/entry
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/entry/index.mdx
Access collection outputs from entry files.
## Overview [#overview]
After defining collections in your config file, collection entries are compiled into JavaScript files that your app can access.
While the compilation will be done by Fumadocs MDX's bundler/runtime plugins, it also generates **entry files** to access the collection outputs.
### Entry Files [#entry-files]
Collection outputs will be generated under the output directory, you can access them from entry files.
See below for a list of available ways to access outputs.
Docs (Meta + Doc)
Doc
```ts
import { docs } from 'collections/server';
import { loader } from 'fumadocs-core/source';
// raw collection
console.log(docs);
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
```ts
import { blogPosts } from 'collections/server';
import { toFumadocsSource } from 'fumadocs-mdx/runtime/server';
import { loader } from 'fumadocs-core/source';
// raw collection
console.log(blogPosts);
export const blog = loader({
baseUrl: '/blog',
source: toFumadocsSource(blogPosts, []),
});
```
## Examples [#examples]
```tsx
import { source } from '@/lib/source';
const page = source.getPage(['slugs']);
if (page) {
// access page data [!code highlight]
console.log(page.data);
// frontmatter properties are also available [!code highlight]
console.log(page.data.title);
}
```
To render the page (on RSC), use `page.data.body` as a component.
```tsx
import { getMDXComponents } from '@/components/mdx';
const MDX = page.data.body;
// set your MDX components with `components` prop
return
MDX
React.js
```mdx
---
title: Hello World
---
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
My Content
```
```tsx
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
export default function Page() {
return (
My Content
);
}
```
### Accordions [#accordions]
My Content
```
> The value of accordion is same as title by default. When an id presents, it will be used as the value instead.
# Fumadocs UI (the default theme of Fumadocs): Auto Type Table
URL: /docs/ui/components/auto-type-table
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/auto-type-table.mdx
Auto-generated type table
You cannot use this in a client component, instead, try the [build-time MDX integration](/docs/integrations/typescript#mdx-integration) instead.
It generates a table for your docs based on TypeScript definitions.
## Usage [#usage]
npm
pnpm
yarn
bun
```bash
npm i fumadocs-typescript
```
```bash
pnpm add fumadocs-typescript
```
```bash
yarn add fumadocs-typescript
```
```bash
bun add fumadocs-typescript
```
Initialize the TypeScript compiler and add it as a MDX component.
```tsx title="components/mdx.tsx"
import defaultComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
import { createGenerator, createFileSystemGeneratorCache } from 'fumadocs-typescript';
import { AutoTypeTable, type AutoTypeTableProps } from 'fumadocs-typescript/ui';
const generator = createGenerator({
// set a cache, necessary for serverless platform like Vercel
cache: createFileSystemGeneratorCache('.next/fumadocs-typescript'),
});
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultComponents,
// [!code ++]
AutoTypeTable: (props: Partial) => (
Hello World
{children}
);
}
```
### Variant [#variant]
Change the default variant.
```tsx
import { Banner } from 'fumadocs-ui/components/banner';
Hello World ;
// customise colors
Hello World
;
```
### Change Layout [#change-layout]
By default, the banner uses a `style` tag to modify Fumadocs layouts (e.g. reduce the sidebar height).
You can disable it with:
```tsx
import { Banner } from 'fumadocs-ui/components/banner';
Hello World ;
```
### Close [#close]
To allow users to close the banner, give the banner an ID.
```tsx
import { Banner } from 'fumadocs-ui/components/banner';
Hello World ;
```
The state will be automatically persisted.
# Fumadocs UI (the default theme of Fumadocs): Code Block
URL: /docs/ui/components/codeblock
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/codeblock.mdx
Displaying Shiki highlighted code blocks
),
...components,
} satisfies MDXComponents;
}
```
### Keep Background [#keep-background]
Use the background color generated by Shiki.
```tsx
import { Pre, CodeBlock } from 'fumadocs-ui/components/codeblock';
;
```
### Icons [#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 UI (the default theme of Fumadocs): Code Block (Dynamic)
URL: /docs/ui/components/dynamic-codeblock
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/dynamic-codeblock.mdx
A codeblock that also highlights code
## Usage [#usage]
### Client Component [#client-component]
```tsx
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
export function MyComp() {
const code = `console.log("Hello World")`;
return
```
### File [#file]
` [#auto-files]
Generate `{children} ;
}
```
# Fumadocs UI (the default theme of Fumadocs): Graph View
URL: /docs/ui/components/graph-view
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/graph-view.mdx
A graph of all pages.
npm
pnpm
yarn
bun
```bash
npx @fumadocs/cli add graph-view
```
```bash
pnpm dlx @fumadocs/cli add graph-view
```
```bash
yarn dlx @fumadocs/cli add graph-view
```
```bash
bun x @fumadocs/cli add graph-view
```
Enable `extractLinkReferences` on Fumadocs MDX.
```ts title="source.config.ts"
import { defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
docs: {
postprocess: {
// [!code ++]
extractLinkReferences: true,
},
},
});
```
## Usage [#usage]
You can use it in MDX files or the layout components (e.g. in `page.tsx`):
```tsx title="page.tsx"
import { GraphView } from '@/components/graph-view';
import { buildGraph } from '@/lib/build-graph';
export function PageBody() {
return (
Server Component only.
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 '@/components/mdx';
const page = source.getPage(['...']);
return (
Table of Contents
```
Or adding it to every page.
```tsx title="page.tsx"
import { DocsPage } from 'fumadocs-ui/layouts/docs/page';
import { InlineTOC } from 'fumadocs-ui/components/inline-toc';
export default function Page() {
// ...
return (
{/* [!code ++] */}
Table of Contents
);
}
```
## Reference [#reference]
### Hello World
### Hello World
```
### Without imports [#without-imports]
You can use the Tailwind CSS utilities without importing it.
```mdx
```
It supports adding step styles to only headings with arbitrary variants.
```mdx
Javascript is weird
Rust is fast
```
Javascript is weird
Rust is fast
### Without `value` [#without-value]
Without a `value`, it detects from the children index. Note that it might cause errors on re-renders, it's not encouraged if the tabs might change.
```mdx
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Javascript is weird
Rust is fast
```
Javascript is weird
Rust is fast
### Shared Value [#shared-value]
By passing an `groupId` property, you can share a value across all tabs with the same
id.
```mdx
Javascript is weird
Rust is fast
```
### Persistent [#persistent]
When `groupId` is specified, their value will be temporarily stored in `sessionStorage`.
To persist the value, you can specify a `persist` prop. The value will be
stored in `localStorage`, with its group ID as storage key.
```mdx
Javascript is weird
Rust is fast
```
### Default Value [#default-value]
Set a default value by passing `defaultIndex`.
```mdx
Javascript is weird
Rust is fast
```
### Link to Tab [#link-to-tab]
Use HTML `id` attribute to link to a specific tab.
```mdx
Javascript is weird
Rust is fast
`Hello World`
```
You can add the hash `#tab-cpp` to your URL and reload, the C++ tab will be activated.
Javascript is weird
Rust is fast
`Hello World`
Additionally, the `updateAnchor` property can be set to `true` in the `Tabs` component
to automatically update the URL hash whenever time a new tab is selected:
```mdx
Javascript is weird
Rust is fast
`Hello World`
```
Hello!
World!
## Advanced Usage [#advanced-usage]
Use it in the primitive way:
```mdx
Hello World
```
npm
Hello World
# Fumadocs UI (the default theme of Fumadocs): Type Table
URL: /docs/ui/components/type-table
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/type-table.mdx
A table for documenting types
{children}
);
}
```
See detailed docs for [`links`](/docs/ui/layouts/links) and [`nav`](/docs/ui/layouts/nav) options.
### References [#references]
Sidebar items are rendered from the page tree you passed to `
{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}
);
}
```
### Layout Tabs (Dropdown) [#layout-tabs]
Layout Tabs are folders with tab-like behaviours, only the content of opened tab will be visible.
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/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';
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';
export default function Layout({ children }: { children: ReactNode }) {
return (
Hello World
,
}}
>
{children}
);
}
```
#### Decoration [#decoration]
Change the icon/styles of layout tabs.
```tsx
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
{chart}
{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]
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...
```
...```
...```
```
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
import { remarkImage } from 'fumadocs-core/mdx-plugins';
export default {
remarkPlugins: [[remarkImage, { 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]
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 (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
Generate markdown for LLM consumption with customizable placeholders
The `remarkLLMs` plugin stringifies the processed Markdown AST to plain Markdown, the output is generated as an ESM export. This is useful for feeding content to LLMs, search indexing, or other text-based processing.
## Usage [#usage]
### Fumadocs MDX [#fumadocs-mdx]
Enable `includeProcessedMarkdown` in your collection config, Fumadocs MDX runs `remarkLLMs` internally when this is set.
```ts title="source.config.ts"
import { defineDocs } from 'fumadocs-mdx/config';
import { type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
// options...
};
export default defineDocs({
docs: {
postprocess: {
includeProcessedMarkdown: llmsOptions,
},
},
});
```
The stringified Markdown is exported as `_markdown` and available via `getText('processed')`, see [Collections](/docs/mdx/collections#includeprocessedmarkdown) for details.
### MDX Compiler [#mdx-compiler]
When using the MDX Compiler (or a custom pipeline), add the plugin:
```ts
import { compile } from '@mdx-js/mdx';
import { remarkLLMs, type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
// The output will be exported as `_markdown`
as: '_markdown',
};
const vfile = await compile('...', {
remarkPlugins: [[remarkLLMs, llmsOptions]],
});
```
## Placeholders [#placeholders]
Placeholders let you keep certain MDX components in the stringified output as special tokens instead of dropping or inlining them. That way you can:
. Rehydrate those tokens later via `renderPlaceholder()`.
. Generate a better Markdown representation with runtime data.
### Using `mdxAsPlaceholder` [#using-mdxasplaceholder]
List component names to treat as placeholders:
```ts
import { type LLMsOptions } from 'fumadocs-core/mdx-plugins/remark-llms';
const llmsOptions: LLMsOptions = {
// [!code ++]
mdxAsPlaceholder: ['Callout', 'Card'],
};
```
In the exported Markdown, `
# Heading 1
## Sub Heading 1
## Sub Heading 2
# Heading 2
{children}
;
}
```
````
{children}
;
}
```
{children}
;
}
```
### Installation [#installation]
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 { defineDocs, defineConfig } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
export default defineConfig();
```
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({
// customise the config file path
// configPath: "source.config.ts"
});
// [!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.
Setup an import alias (recommended):
```json title="tsconfig.json"
{
"compilerOptions": {
"paths": {
// [!code ++]
"collections/*": ["./.source/*"]
}
}
}
```
### Integrate with Fumadocs [#integrate-with-fumadocs]
You can create a `lib/source.ts` file and obtain Fumadocs source from the `docs` collection output.
```ts title="lib/source.ts"
import { docs } from 'collections/server';
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
The `.source` folder will be generated when you run `next dev` or `next build`.
### Done [#done]
You can now write content in `content/docs` folder.
### Installation [#installation]
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 { defineDocs } from 'fumadocs-mdx/config';
export const docs = defineDocs({
dir: 'content/docs',
});
```
Add the Vite plugin:
Vite
Waku
```ts title="vite.config.ts"
import { defineConfig } from 'vite';
import mdx from 'fumadocs-mdx/vite';
import * as MdxConfig from './source.config';
export default defineConfig({
plugins: [
// [!code ++]
mdx(MdxConfig),
// ...
],
});
```
```ts title="waku.config.ts"
import { type Config, defineConfig } from 'waku/config';
import mdx from 'fumadocs-mdx/vite';
import * as MdxConfig from './source.config.js';
import type { UserConfig } from 'vite';
export default defineConfig({
vite: {
plugins: [
// [!code ++]
mdx(MdxConfig),
tsconfigPaths(),
],
resolve: {
tsconfigPaths: true,
},
} satisfies UserConfig as Config['vite'],
});
```
Setup an import alias (recommended):
```json title="tsconfig.json"
{
"compilerOptions": {
"paths": {
// [!code ++]
"collections/*": ["./.source/*"]
}
}
}
```
### Integrate with Fumadocs [#integrate-with-fumadocs]
To integrate with Fumadocs, make a `lib/source.ts` file:
```ts title="app/lib/source.ts"
import { docs } from 'collections/server';
import { loader } from 'fumadocs-core/source';
export const source = loader({
baseUrl: '/docs',
source: docs.toFumadocsSource(),
});
```
The `.source` folder will be generated when you run development server or production build.
### Done [#done]
You can now write content in `content/docs` folder.
## What is Next? [#what-is-next]
{frontmatter.title}
{frontmatter.title}
{/* pass MDX components and render it */}
);
}
```
### Using as Page [#using-as-page]
On Next.js, you can use `page.mdx` instead of `page.tsx` for creating a new page under the app directory.
```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}
### Hello World
```
### Hello World [#hello-world]
You no longer need to use the step component anymore.
# Fumadocs UI (the default theme of Fumadocs): 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.
<>
<>
This heading looks good!
It applies the Typography styles, wrap your content here.This heading looks good!
It applies the Typography styles, wrap your content here.Hello World
;
}
export function TOCPopover(props: TOCPopoverProps) {
return Popover
;
}
```
Hello World
;
}
```
Hello World
;
}
```
#### Page Tree [#page-tree-step]
You can either hardcode the page tree, or write some code to generate one.
See [Definitions of Page Tree](/docs/headless/page-tree).
Pass your page tree to `DocsLayout` (usually in a `layout.tsx`):
```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}
);
}
```
The page tree is like a smarter "sidebar items", they will be referenced everywhere in the UI for navigation elements, such as the page footer.
#### Page Content [#page-content-step]
For docs page, it's the same logic:
* Define path params (`slugs`).
* Fetch page content from path params.
* Render the content (inside the `DocsPage` component).
You may need table of contents, which can be generated on your own, or using the [`getTableOfContents`](/docs/headless/utils/get-toc) utility (Markdown/MDX only).
```tsx
import { DocsPage, DocsBody } from 'fumadocs-ui/layouts/docs/page';
import { getPage } from './my-content-source';
import { notFound } from 'next/navigation';
export default function Page({ params }: { params: { slug?: string[] } }) {
const page = getPage(params.slug);
if (!page) notFound();
return (
{page.render()}
);
}
```
#### Pre-rendering [#pre-rendering-step]
The mechanism for pre-rendering differs depending on your React.js framework.
It's important to pre-render pages (especially the frequently visited ones) to improve initial load time.
Define the [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) function to populate dynamic & catch-all routes.
When pre-rendering pages from a remote source, make sure to optimize repeated reads during the build phase.
For example, if you're fetching content via GitHub API, it is better to clone the repository content locally for pre-rendering.
Before
After
```text
/docs/* -> GET github.com
/docs/introduction -> GET github.com
/docs/my-page -> GET github.com
Error: API Ratelimit
```
```text
start -> git clone
/docs/* -> ls
/docs/introduction -> read file
/docs/my-page -> read file
```
#### Document Search [#document-search-step]
This can be difficult considering your content may not be necessarily Markdown/MDX.
For Markdown and MDX, the built-in [Search API](/docs/headless/search/orama) + search index usage is adequate for most use cases.
Otherwise, you will have to bring your own implementation.
We recommend 3rd party solutions like Orama or Algolia Search. They are more flexible than the built-in Search API, and is easier to integrate with remote sources.
Fumadocs offers a variant of [Search Integrations](/docs/headless/search).
{page.data.title}
### Generate Styles [#generate-styles-step]
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 Plugin [#configure-plugin-step]
Create the OpenAPI server instance & `
lib/openapi.ts
components/api-page.tsx
lib/source.ts
```ts
import { createOpenAPI } from 'fumadocs-openapi/server';
export const openapi = createOpenAPI({
// the OpenAPI schema, you can also give it an external URL.
input: ['./openapi.json'],
});
```
```tsx
import { createClientAPIPage } from 'fumadocs-openapi/ui/create-client';
export const ClientAPIPage = createClientAPIPage();
```
```ts
import { openapiPlugin } from 'fumadocs-openapi/server';
import { loader } from 'fumadocs-core/source';
export const source = loader({
// [!code ++] optional: adds a badge to each page item in page tree
plugins: [openapiPlugin()],
});
```
See [`createOpenAPI()`](/docs/integrations/openapi/server) & [`
### Generate Pages [#generate-pages-step]
You can generate pages dynamically by integrating into [Loader API](/docs/headless/source-api/source).
```ts title="lib/source.ts"
import { loader, multiple } from 'fumadocs-core/source';
import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
import { docs } from 'collections/server';
import { openapi } from '@/lib/openapi';
export const source = loader(
// [!code ++:6]
multiple({
docs: docs.toFumadocsSource(),
openapi: await openapiSource(openapi, {
baseDir: 'openapi',
}),
}),
{
baseUrl: '/docs',
plugins: [openapiPlugin()],
// ...
},
);
```
### Update References to `source` [#update-references-to-source-step]
`openapiSource()` is a server-side API that generates pages directly to your `loader()`, hence allowing dynamic generation (e.g. different page tree as schema changes).
But **it will change the type of your pages**, explicit handling of OpenAPI pages is necessary.
```ts
import { source } from '@/lib/source';
const page = source.getPage(['...']);
if (page.data.type === 'openapi') {
// page data for generated OpenAPI pages
console.log(page.data);
} else {
// original flow...
}
```
Update all references to the pages of `source`, for example:
```ts title="lib/source.ts"
import type { InferPageType } from 'fumadocs-core/source';
/**
* return page content for LLMs
*/
export async function getLLMText(page: InferPageType) {
// [!code ++:4]
if (page.data.type === 'openapi') {
// e.g. return the stringified OpenAPI schema
return JSON.stringify(page.data.getSchema().bundled, null, 2);
}
// your original flow below...
}
```
Run a type check to verify before continuing, e.g.
npm
pnpm
yarn
bun
```bash
npm run types:check
```
```bash
pnpm run types:check
```
```bash
yarn types:check
```
```bash
bun run types:check
```
### Render Page [#render-page-step]
Pass a client payload from server, then render the page using the `
{page.title}
{page.description}
{/* pass the payload data */}
);
} else {
content = clientLoader.useContent(page.path, page);
}
return (
{content}
);
}
```
You can see the full [Tanstack Start example](https://github.com/fuma-nama/fumadocs/blob/dev/examples/tanstack-start-openapi).
After configurating Fumadocs OpenAPI, you should be able to view the generated API pages after starting your app.
A story captures the rendered state of a UI component. It's an object with annotations that describe the component's behavior and appearance given a set of arguments.
{title}
; } ```{title}
; } ```