` tag: a.mdx b.mdx ```mdx ## Hello World

This is included

This is not included. ``` ```mdx Include the content from `a.mdx`: a.mdx#test ``` In Markdown: a.md b.md ```md ## Hello World :::section{#test} This is included ::: This is not included. ``` ```md Include the content from `a.mdx`: ::include[a.md#test] ``` Heading [#heading] Include contents under a certain heading. a.mdx b.mdx ```mdx ## Included Section I'm here! ## Not Included Some random text. ``` ```mdx Content under the heading: a.mdx#included-section ``` In Markdown: a.md b.md ```md ## Included Section I'm here! ## Not Included Some random text. ``` ```md Content under the heading: ::include[a.mdx#included-section] ``` # Fumadocs MDX (the built-in content source): Getting Started URL: /docs/mdx Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/index.mdx Introducing Fumadocs MDX, the official content source of Fumadocs. Introduction [#introduction] Fumadocs MDX is a tool to transform content into type-safe data, similar to Content Collections. It is not a full CMS but rather a content processing layer for React frameworks, you can use it to handle blog posts and other contents. What is a Collection? [#what-is-a-collection] **Collection** refers to a collection containing a certain type of files. You can define collections in the config file (`source.config.ts`). Fumadocs MDX transforms collections into type-safe data, accessible in your app. Available collections: Compile Markdown & MDX files into a React Server Component, with useful properties like **Table of Contents**. ```ts title="source.config.ts" import { defineCollections } from 'fumadocs-mdx/config'; export const test = defineCollections({ type: 'doc', dir: 'content/docs', }); ``` Transform YAML/JSON files into an array of data. ```ts title="source.config.ts" import { defineCollections } from 'fumadocs-mdx/config'; export const test = defineCollections({ type: 'meta', dir: 'content/docs', }); ``` Combination of `meta` and `doc` collections, which is needed for Fumadocs. ```ts title="source.config.ts" import { defineDocs } from 'fumadocs-mdx/config'; export const docs = defineDocs({ dir: 'content/docs', docs: { // options for `doc` collection }, meta: { // options for `meta` collection }, }); ``` For example, a `doc` collection will transform the `.md` and `.mdx` files: We will cover in [Accessing Collections](/docs/mdx/entry) later on how to access collection outputs. Installation [#installation] Configure Fumadocs MDX on: Using Fumadocs MDX with Next.js. Using Fumadocs MDX with Vite. Using Fumadocs MDX with a JavaScript runtime. FAQ [#faq] Built-in Properties [#built-in-properties] These properties are exported from MDX files by default. | Property | Description | | --------------------- | ----------------------------------------------- | | `frontmatter` | Frontmatter | | `toc` | Table of Contents | | `structuredData` | Structured Data, useful for implementing search | | `extractedReferences` | For analyzing `hrefs` references | Customise Frontmatter [#customise-frontmatter] Use the [`schema`](/docs/mdx/collections#schema-1) option to pass a validation schema to validate frontmatter and define its output properties. Customise MDX Compiler [#customise-mdx-compiler] Fumadocs MDX uses [MDX Compiler](https://mdxjs.com/packages/mdx) to compile MDX files into JavaScript files. The [default preset](/docs/mdx/mdx) includes a set of plugins and configurations out-of-the-box. You can customise it on [Global Config](/docs/mdx/global#mdx-options) or [Collection Config](/docs/mdx/collections#mdxoptions). # Fumadocs MDX (the built-in content source): Last Modified Time URL: /docs/mdx/last-modified Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/last-modified.mdx Output the last modified time of a document Usage [#usage] You can add the plugin from the config file. Please ensure you have Git installed on your machine, and **the repository is not shallow cloned**, as it relies on your local Git history. ```ts title="source.config.ts" import { defineConfig } from 'fumadocs-mdx/config'; import lastModified from 'fumadocs-mdx/plugins/last-modified'; export default defineConfig({ // [!code ++] plugins: [lastModified()], }); ``` Access the Property [#access-the-property] After doing this, a `lastModified` property will be exported for each document (as `Date`). ```ts import { source } from '@/lib/source'; const page = source.getPage(['...']); console.log(page.data.lastModified); // or with lazy loading const { lastModified } = await page.data.load(); console.log(lastModified); ``` # Fumadocs MDX (the built-in content source): MDX Presets URL: /docs/mdx/mdx Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/mdx.mdx Customise the default configurations for MDX processor. Fumadocs MDX provides MDX presets to simplify configurations of features like **syntax highlighting**. Default Preset [#default-preset] A preset designed for documentation sites, it is enabled by default for global MDX options. To override the defaults, it accepts an interface inherited from [`ProcessorOptions`](https://mdxjs.com/packages/mdx/#processoroptions): Remark Plugins [#remark-plugins] These plugins are applied by default: * [Remark Image](/docs/headless/mdx/remark-image) - Handle images. * [Remark Heading](/docs/headless/mdx/headings) - Extract table of contents. * [Remark Structure](/docs/headless/mdx/structure) - Generate search indexes. Add other remark plugins with: Global Config Collection Config ```ts import { defineConfig } from 'fumadocs-mdx/config'; import { myPlugin } from './remark-plugin'; export default defineConfig({ mdxOptions: { remarkPlugins: [myPlugin], // You can also pass a function to control the order of remark plugins. remarkPlugins: (v) => [myPlugin, ...v], }, }); ``` ```ts import { defineCollections, applyMdxPreset } from 'fumadocs-mdx/config'; import { myPlugin } from './remark-plugin'; export const blog = defineCollections({ type: 'doc', mdxOptions: applyMdxPreset({ remarkPlugins: [myPlugin], // You can also pass a function to control the order of remark plugins. remarkPlugins: (v) => [myPlugin, ...v], }), }); ``` Rehype Plugins [#rehype-plugins] These plugins are applied by default: * [Rehype Code](/docs/headless/mdx/rehype-code) - Syntax highlighting. * [Rehype TOC](/docs/headless/mdx/headings#rehype-toc) - Export table of contents. Same as remark plugins, you can pass an array or a function to add other rehype plugins. Global Config Collection Config ```ts import { defineConfig } from 'fumadocs-mdx/config'; import { myPlugin } from './rehype-plugin'; export default defineConfig({ mdxOptions: { rehypePlugins: (v) => [myPlugin, ...v], }, }); ``` ```ts import { defineCollections, applyMdxPreset } from 'fumadocs-mdx/config'; import { myPlugin } from './rehype-plugin'; export const blog = defineCollections({ type: 'doc', mdxOptions: applyMdxPreset({ rehypePlugins: (v) => [myPlugin, ...v], }), }); ``` Customise Built-in Plugins [#customise-built-in-plugins] Customise the options of built-in plugins like: Global Config Collection Config ```ts import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { rehypeCodeOptions: { // options }, remarkImageOptions: { // options }, remarkHeadingOptions: { // options }, }, }); ``` ```ts import { defineCollections, applyMdxPreset } from 'fumadocs-mdx/config'; export const blog = defineCollections({ type: 'doc', mdxOptions: applyMdxPreset({ rehypeCodeOptions: { // options }, remarkImageOptions: { // options }, remarkHeadingOptions: { // options }, }), }); ``` # Fumadocs MDX (the built-in content source): Performance URL: /docs/mdx/performance Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/performance.mdx The performance of Fumadocs MDX Overview [#overview] Fumadocs MDX is a bundler plugin, in other words, it has a higher performance bottleneck. With bundlers like Webpack and Turbopack, it is enough for large docs sites with nearly 500+ MDX files, which is sufficient for almost all use cases. Since Fumadocs MDX works with your bundler, you can import any files including client components in your MDX files. This allows high flexibility and ensures everything is optimized by default. Image Optimization [#image-optimization] Fumadocs MDX resolves images into static imports with [Remark Image](/docs/headless/mdx/remark-image). Therefore, your images will be optimized automatically for your React framework (e.g. Next.js Image API). ```mdx ![Hello](./hello.png) or in public folder ![Hello](/hello.png) ``` Yields: ```mdx import HelloImage from './hello.png'; Hello

```

Caveats [#caveats] Although Fumadocs MDX can handle nearly 500+ files, it could be slow and inefficient. A huge amount of MDX files can cause extremely high memory usage during build and development mode. This is because of: * Bundlers do a lot of work under the hood to bundle MDX and JavaScript files and optimize performance. * Bundlers are not supposed to compile hundreds of MDX files. Solutions [#solutions] The main solution is to make the compilation on-demand, such that content is only loaded when it's being requested. Remote Source [#remote-source] Create your custom content source with remoting content loading. You can ensure your custom source doesn't need to pre-compile content files, it can process them on-demand with SSG which can **improve your build speed.** However, you cannot leverage build time optimizations (e.g. bundling). See [Custom Source](/docs/integrations/content/custom) for implementing custom sources. Lazy Loading [#lazy-loading] See [Lazy Loading](/docs/mdx/async). # Fumadocs MDX (the built-in content source): Generate Types URL: /docs/mdx/typegen Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/typegen.mdx Generate types without running dev/build server Overview [#overview] You can run `fumadocs-mdx` to generate types & entry files (the `.source` folder). Optionally, you can run it in post install to ensure types are generated when initializing the project. ```json title="package.json" { "scripts": { "postinstall": "fumadocs-mdx" } } ``` If your project uses a custom path for configuration file or output directory, you can provide them as command arguments: npm pnpm yarn bun ```bash npx fumadocs-mdx "config-path" "output-dir" ``` ```bash pnpm dlx fumadocs-mdx "config-path" "output-dir" ``` ```bash yarn dlx fumadocs-mdx "config-path" "output-dir" ``` ```bash bun x fumadocs-mdx "config-path" "output-dir" ``` * `config-path`: Fumadocs MDX config file, default to `source.config.ts`. * `output-dir`: Directory of generated files, default to `.source`. # Fumadocs MDX (the built-in content source): Workspace URL: /docs/mdx/workspace Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/mdx/workspace.mdx Use Fumadocs MDX in multiple workspace. Overview [#overview] **Workspace** in Fumadocs MDX, refers to an independent project with its own config and content. Fumadocs MDX Workspace is not limited to the traditional meaning of workspace in package managers. They do not need to have its own `package.json`, only a config file is needed. To define a workspace, add: ```ts title="source.config.ts" import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ workspaces: { 'my-workspace': { dir: 'my-workspace', config: await import('./my-workspace/source.config.ts'), }, }, }); ``` When writing content in a workspace, note that: * `cwd` refers to the **current workspace directory**. * configs will not inherit, workspaces are always independent. By running dev or build server, you should see collection entries from all workspaces to be generated. Accessing Collections [#accessing-collections] You can access the generated files of a workspace at `.source/{workspace}/*`. For example: ```ts title="lib/source.ts" import { docs } from 'fumadocs-mdx:collections/my-workspace/server'; ``` > > The output location of root workspace is not changed. > To integrate multiple sources in Fumadocs, use [`multiple`](/docs/headless/source-api/source#multiple-sources): ```ts title="lib/source.ts" import { loader, multiple } from 'fumadocs-core/source'; import { docs } from 'fumadocs-mdx:collections/server'; import * as MyWorkspace from 'fumadocs-mdx:collections/my-workspace/server'; export const source = loader( multiple({ root: docs.toFumadocsSource(), 'my-workspace': MyWorkspace.docs.toFumadocsSource(), }), { baseUrl: '/docs', }, ); ``` When to Use [#when-to-use] In some setups, you might have multiple Fumadocs MDX configs with their own content directory. With workspaces, you can integrate them into one Fumadocs MDX config, and access all collections of each workspace. This is crucial for use cases like storing content across multiple repos, a simplified setup would be: * let your main docs repo be $A$, and other repos be $T_n$ * for each repo $T_n$: * $T_n$ has $A$ as a git submodule. * $T_n$ defines its own config `source.config.ts` and work independently. * when a commit is made to the content in $T_n$, it triggers a GitHub action (or CI), which creates a new deployment on $A$. * when a deployment is triggered on $A$: * Fumadocs MDX handles each $T_n$ as a workspace. * each workspace generates its own collection entries, e.g. `fumadocs-mdx:collections/{repo}/server`. * Fumadocs `loader()` integrate multiple sources into one. # Fumadocs (Framework Mode): Deploying URL: /docs/deploying Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/deploying/index.mdx Deploy your Fumadocs app Overview [#overview] Your Fumadocs app is powered by the underlying React framework (e.g. Next.js), you will need to check the relevant docs of your React framework for deployment guides. * [Next.js](https://nextjs.org/docs/app/getting-started/deploying) * [React Router](https://reactrouter.com/start/framework/deploying) * [Tanstack Start](https://tanstack.com/start/latest/docs/framework/react/guide/hosting) * [Waku](https://waku.gg/#deployment) If you are looking to host the app as a SPA app (fully static, hostable on CDN), see [Static Build](/docs/deploying/static). There's some extra notes on specific combinations: Next.js + Cloudflare [#nextjs--cloudflare] Use [https://opennext.js.org/cloudflare](https://opennext.js.org/cloudflare), Fumadocs doesn't work on Edge runtime. Next.js + Docker [#nextjs--docker] If you want to deploy your Fumadocs app using Docker with **Fumadocs MDX configured**, make sure to add the `source.config.ts` file and your `next.config.js` file to the `WORKDIR` in the Dockerfile. The following snippet is taken from the official [Next.js Dockerfile Example](https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile): ```zsh title="Dockerfile" # syntax=docker.io/docker/dockerfile:1 FROM node:18-alpine AS base # Install dependencies only when needed FROM base AS deps # Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed. RUN apk add --no-cache libc6-compat WORKDIR /app # Install dependencies based on the preferred package manager [!code highlight] COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* source.config.ts next.config.* ./ RUN \ if [ -f yarn.lock ]; then yarn --frozen-lockfile; \ elif [ -f package-lock.json ]; then npm ci; \ elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \ else echo "Lockfile not found." && exit 1; \ fi # Rebuild the source code only when needed FROM base AS builder WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . # Next.js collects completely anonymous telemetry data about general usage. # Learn more here: https://nextjs.org/telemetry # Uncomment the following line in case you want to disable telemetry during the build. # ENV NEXT_TELEMETRY_DISABLED=1 RUN \ if [ -f yarn.lock ]; then yarn run build; \ elif [ -f package-lock.json ]; then npm run build; \ elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \ else echo "Lockfile not found." && exit 1; \ fi # Production image, copy all the files and run next FROM base AS runner WORKDIR /app ENV NODE_ENV=production # Uncomment the following line in case you want to disable telemetry during runtime. # ENV NEXT_TELEMETRY_DISABLED=1 RUN addgroup --system --gid 1001 nodejs RUN adduser --system --uid 1001 nextjs COPY --from=builder /app/public ./public # Automatically leverage output traces to reduce image size # https://nextjs.org/docs/advanced-features/output-file-tracing COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./ COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static USER nextjs EXPOSE 3000 ENV PORT=3000 # server.js is created by next build from the standalone output # https://nextjs.org/docs/pages/api-reference/config/next-config-js/output ENV HOSTNAME="0.0.0.0" CMD ["node", "server.js"] ``` This ensures Fumadocs MDX can access your configuration file during builds. # Fumadocs (Framework Mode): Static Build URL: /docs/deploying/static Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/deploying/static.mdx Output static website with Fumadocs. Setup [#setup] By default, Fumadocs use a server-first approach which always requires a running server to serve. You can output a static build by configuring your React framework.

Search [#1-search] 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 [#2-deployment] 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.

# Fumadocs (Framework Mode): Access Control URL: /docs/guides/access-control Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/guides/access-control.mdx Limit the access of content. Overview [#overview] Thanks to the flexible design, it is simple to implement access control with Fumadocs. Loader API [#loader-api] If you are using [`loader()`](/docs/headless/source-api) API, you can create the loaders on-demand, and filter files from content source to restrict accessible content. For example, this setup with Fumadocs MDX allows only MDX files with frontmatter `permission: public` to be shown. ```ts title="lib/source.ts" import { docs } from 'fumadocs-mdx:collections/server'; import { loader, update } from 'fumadocs-core/source'; const filteredSource = update(docs.toFumadocsSource()) .files((files) => files.filter((file) => { // keep meta files (e.g. `meta.json`) if (file.type === 'meta') return true; // access file data (type-safe) return file.data.permission === 'public'; }), ) .build(); export const source = loader(filteredSource, { baseUrl: '/docs', }); ``` Or with more complicated setup, you may turn `source` into a factory function. lib/source.ts References ```ts import { docs } from 'fumadocs-mdx:collections/server'; import { loader, update } from 'fumadocs-core/source'; // uncached, it's better to cache it in-memory for real use case. export function createSource(permission: 'public' | 'admin') { const filteredSource = update(docs.toFumadocsSource()) .files((files) => files.filter((file) => { if (file.type === 'meta') return true; return file.data.permission === permission; }), ) .build(); return loader(filteredSource, { baseUrl: '/docs', }); } ``` ```ts // [!code --] import { source } from '@/lib/source'; // [!code ++:4] import { createSource } from '@/lib/source'; const user = await getUser(); const source = createSource(user.permission); const page = source.getPage(params.slugs); ``` Advantages [#advantages] What is special with this approach is that **the access is limited at input level**, rather than at rendering phase or build-time. This guarantees the protected content is filtered entirely, and without compromise on flexibility. Custom Implementation [#custom-implementation] Without using Loader API, you can also implement your access control at framework-level (e.g. via Next.js routing & proxy). For example, to limit access to certain pages: ```tsx title="page.tsx" import { notFound } from 'next/navigation'; import { source } from '@/lib/source'; export default async function Page({ params }) { const { slugs } = await params; const user = await getUser(); const page = source.getPage(slugs); if (!page) notFound(); if (page.data.permission !== user.permission) notFound(); // render page... } ``` Note that it is up to you to manage the page tree (sidebar items), search and other details. This approach offers the best flexibility, but it doesn't rely on Fumadocs itself for access control, the setup may take longer and be more complicated. It is better to consult the docs of your React.js framework when implementing. # Fumadocs (Framework Mode): Export PDF URL: /docs/guides/export-pdf Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/guides/export-pdf.mdx Export docs pages as PDF documents Overview [#overview] In general, we strongly recommend you to download the entire website (HTML files, etc) for offline browsing. In case if you want to export the page as a PDF, you can follow this guide. Setup [#setup] Use Puppeteer to export PDF files. ```ts title="scripts/export-pdf.ts" import puppeteer from 'puppeteer'; import fs from 'node:fs/promises'; import path from 'node:path'; const browser = await puppeteer.launch(); const outDir = 'pdfs'; // update this [!code highlight] const urls = ['/docs/ui', '/docs/ui/customisations']; async function exportPdf(pathname: string) { const page = await browser.newPage(); await page.goto('http://localhost:3000' + pathname, { waitUntil: 'networkidle2', }); await page.pdf({ path: path.join(outDir, pathname.slice(1).replaceAll('/', '-') + '.pdf'), width: 950, printBackground: true, }); console.log(`PDF generated successfully for ${pathname}`); await page.close(); } await fs.mkdir(outDir, { recursive: true }); await Promise.all(urls.map(exportPdf)); await browser.close(); ``` Add the following to your Tailwind CSS file to disable navigation elements when printing: ```css @media print { #nd-docs-layout { --fd-sidebar-width: 0px !important; } #nd-sidebar { display: none; } } ``` You can now run the script: ```bash bun ./scripts/export-pdf.ts ``` Invisible Contents [#invisible-contents] For invisible contents in accordions/tabs, you may need to temporarily override the MDX components. For example: ```tsx title="mdx-components.tsx" import defaultMdxComponents from 'fumadocs-ui/mdx'; import type { MDXComponents } from 'mdx/types'; import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; // you may use environment variable here [!code highlight] const isPrinting = true; export function getMDXComponents(components?: MDXComponents) { const PrintingAccordion: typeof Accordion = (props) => (

{props.title}

{props.children}

); return { ...defaultMdxComponents, // updated accordions: Accordion: isPrinting ? PrintingAccordion : Accordion, Accordions: isPrinting ? 'div' : 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. # Fumadocs (Framework Mode): RSS Feed URL: /docs/guides/rss Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/guides/rss.mdx Generate a RSS feed for your docs/blog. Setup [#setup] You can create the feed object: ```ts title="lib/rss.ts" import { Feed } from 'feed'; import { source } from '@/lib/source'; const baseUrl = 'https://fumadocs.dev'; export function getRSS() { const feed = new Feed({ title: 'Fumadocs Blog', id: `${baseUrl}/blog`, link: `${baseUrl}/blog`, language: 'en', image: `${baseUrl}/banner.png`, favicon: `${baseUrl}/icon.png`, copyright: 'All rights reserved 2025, Fuma Nama', }); for (const page of source.getPages()) { feed.addItem({ id: page.url, title: page.data.title, description: page.data.description, link: `${baseUrl}${page.url}`, date: new Date(page.data.lastModified), author: [ { name: 'Fuma', }, ], }); } return feed.rss2(); } ``` And expose it using a server loader/route handler like: Next.js React Router Tanstack Start ```ts title="app/rss.xml/route.ts" import { getRSS } from '@/lib/rss'; export const revalidate = false; export function GET() { return new Response(getRSS()); } ``` ```ts // app/routes/rss.ts import { getRSS } from '@/lib/rss'; export async function loader() { return new Response(getRSS()); } // app/routes.ts import { route, type RouteConfig } from '@react-router/dev/routes'; export default [ // ... route('rss.xml', 'routes/rss.ts'), ] satisfies RouteConfig; ``` ```ts title="src/routes/rss[.]xml.ts" import { createFileRoute } from '@tanstack/react-router'; import { getRSS } from '@/lib/rss'; export const Route = createFileRoute('/rss.xml')({ server: { handlers: { GET: async () => new Response(getRSS()), }, }, }); ``` Next.js Metadata [#nextjs-metadata] You can add an alternates object to the metadata object with your feed’s title and URL. ```ts title="app/layout.tsx" import type { Metadata } from 'next'; export const metadata: Metadata = { alternates: { types: { 'application/rss+xml': [ { title: 'Fumadocs Blog', url: 'https://fumadocs.dev/blog/index.xml', }, ], }, }, }; ``` # Fumadocs (Framework Mode): Feedback URL: /docs/integrations/feedback Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/integrations/feedback.mdx Receive feedback from your users Overview [#overview] Feedback is crucial for knowing what your reader thinks, and help you to further improve documentation content. You can integrate a simple feedback system with Fumadocs. Installation [#installation] Install it using **Fumadocs CLI**. npm pnpm yarn bun ```bash npx @fumadocs/cli@latest add feedback ``` ```bash pnpm dlx @fumadocs/cli@latest add feedback ``` ```bash yarn dlx @fumadocs/cli@latest add feedback ``` ```bash bun x @fumadocs/cli@latest add feedback ``` Page Feedback [#page-feedback] To create a page-level feedback UI, add the `` component to your docs page: ```tsx import { DocsPage } from 'fumadocs-ui/layout/docs/page'; import { Feedback } from '@/components/feedback/client'; import posthog from 'posthog-js'; export default async function Page() { return ( {/* at the bottom of page */} { 'use server'; await posthog.capture('on_rate_docs', feedback); }} /> ); } ``` * `onSendAction`: fired when user submit feedback. You can specify a server action, or any function (in client component) to handle the user feedback. For example, to report user feedback as a `on_rate_docs` event on PostHog. Feedback Block [#feedback-block] You can also configure block-level feedback (e.g. a feedback popover for each paragraph). Add the `remark-feedback-block` Remark plugin: ```tsx title="source.config.ts (Fumadocs MDX)" import { remarkFeedbackBlock } from 'fumadocs-core/mdx-plugins/remark-feedback-block'; import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { // [!code ++] remarkPlugins: [remarkFeedbackBlock], }, }); ``` Then, define the `FeedbackBlock` MDX component: ```tsx title="mdx-components.tsx" import { FeedbackBlock } from '@/components/feedback/client'; import defaultComponents from 'fumadocs-ui/mdx'; import type { MDXComponents } from 'mdx/types'; export function getMDXComponents(components?: MDXComponents): MDXComponents { return { ...defaultComponents, FeedbackBlock: (props) => ( {children} ), ...components, }; } ``` * `onSendAction`: fired when user submit feedback. `remark-feedback-block` generates a block ID from its content and order in the page, hence it is also possible to track the blocks from 3rd party services. Integrating with GitHub Discussion [#integrating-with-github-discussion] To report your feedback to GitHub Discussion, you can copy this file as a starting point: ```ts title='lib/github.ts' import { App, Octokit } from 'octokit'; import { blockFeedback, BlockFeedback, pageFeedback, type ActionResponse, type PageFeedback, } from '@/components/feedback/schema'; export const repo = 'fumadocs'; export const owner = 'fuma-nama'; export const DocsCategory = 'Docs Feedback'; let instance: Octokit | undefined; async function getOctokit(): Promise { if (instance) return instance; const appId = process.env.GITHUB_APP_ID; const privateKey = process.env.GITHUB_APP_PRIVATE_KEY; if (!appId || !privateKey) { throw new Error('No GitHub keys provided for Github app, docs feedback feature will not work.'); } const app = new App({ appId, privateKey, }); const { data } = await app.octokit.request('GET /repos/{owner}/{repo}/installation', { owner, repo, headers: { 'X-GitHub-Api-Version': '2022-11-28', }, }); instance = await app.getInstallationOctokit(data.id); return instance; } interface RepositoryInfo { id: string; discussionCategories: { nodes: { id: string; name: string; }[]; }; } let cachedDestination: RepositoryInfo | undefined; async function getFeedbackDestination() { if (cachedDestination) return cachedDestination; const octokit = await getOctokit(); const { repository, }: { repository: RepositoryInfo; } = await octokit.graphql(` query { repository(owner: "${owner}", name: "${repo}") { id discussionCategories(first: 25) { nodes { id name } } } } `); return (cachedDestination = repository); } export async function onPageFeedbackAction(feedback: PageFeedback): Promise { 'use server'; feedback = pageFeedback.parse(feedback); return createDiscussionThread( feedback.url, `[${feedback.opinion}] ${feedback.message}\n\n> Forwarded from user feedback.`, ); } export async function onBlockFeedbackAction(feedback: BlockFeedback): Promise { 'use server'; feedback = blockFeedback.parse(feedback); return createDiscussionThread( feedback.url, `> ${feedback.blockBody ?? feedback.blockId}\n\n${feedback.message}\n\n> Forwarded from user feedback.`, ); } async function createDiscussionThread(pageId: string, body: string) { const octokit = await getOctokit(); const destination = await getFeedbackDestination(); const category = destination.discussionCategories.nodes.find( (category) => category.name === DocsCategory, ); if (!category) throw new Error(`Please create a "${DocsCategory}" category in GitHub Discussion`); const title = `Feedback for ${pageId}`; const { search: { nodes: [discussion], }, }: { search: { nodes: { id: string; url: string }[]; }; } = await octokit.graphql(` query { search(type: DISCUSSION, query: ${JSON.stringify(`${title} in:title repo:${owner}/${repo} author:@me`)}, first: 1) { nodes { ... on Discussion { id, url } } } }`); if (discussion) { const result: { addDiscussionComment: { comment: { id: string; url: string }; }; } = await octokit.graphql(` mutation { addDiscussionComment(input: { body: ${JSON.stringify(body)}, discussionId: "${discussion.id}" }) { comment { id, url } } }`); return { githubUrl: result.addDiscussionComment.comment.url, }; } else { const result: { discussion: { id: string; url: string }; } = await octokit.graphql(` mutation { createDiscussion(input: { repositoryId: "${destination.id}", categoryId: "${category.id}", body: ${JSON.stringify(body)}, title: ${JSON.stringify(title)} }) { discussion { id, url } } }`); return { githubUrl: result.discussion.url, }; } } ``` 1. Create your own GitHub App and obtain its app ID and private key. 2. Fill required environment variables. 3. Replace constants like `owner`, `repo`, and `DocsCategory`. 4. Use the `onPageFeedbackAction` & `onBlockFeedbackAction` in your feedback components. # Fumadocs (Framework Mode): AI & LLMs URL: /docs/integrations/llms Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/integrations/llms.mdx Integrate AI functionality to Fumadocs. Docs for LLM [#docs-for-llm] You can make your docs site more AI-friendly with dedicated docs content for large language models. To begin, make a `getLLMText` function that converts pages into static MDX content. In **Fumadocs MDX**, you can do: ```ts title="lib/get-llm-text.ts" import { source } from '@/lib/source'; import type { InferPageType } from 'fumadocs-core/source'; export async function getLLMText(page: InferPageType) { const processed = await page.data.getText('processed'); return `# ${page.data.title} (${page.url}) ${processed}`; } ``` It requires `includeProcessedMarkdown` to be enabled: ```ts title="source.config.ts" import { defineDocs } from 'fumadocs-mdx/config'; export const docs = defineDocs({ docs: { // [!code ++:3] postprocess: { includeProcessedMarkdown: true, }, }, }); ``` llms-full.txt [#llms-fulltxt] A version of docs for AIs to read. Next.js React Router Tanstack Start ```ts title="app/llms-full.txt/route.ts" import { source } from '@/lib/source'; import { getLLMText } from '@/lib/get-llm-text'; // cached forever export const revalidate = false; export async function GET() { const scan = source.getPages().map(getLLMText); const scanned = await Promise.all(scan); return new Response(scanned.join('\n\n')); } ``` ```ts title="app/routes.ts" import { index, route, type RouteConfig } from '@react-router/dev/routes'; export default [ // [!code ++] route('llms-full.txt', 'routes/llms-full.ts'), ] satisfies RouteConfig; ``` ```ts title="app/routes/llms-full.ts" import { source } from '@/lib/source'; import { getLLMText } from '@/lib/get-llm-text'; export async function loader() { const scan = source.getPages().map(getLLMText); const scanned = await Promise.all(scan); return new Response(scanned.join('\n\n')); } ``` ```ts title="src/routes/llms-full[.]txt.ts" import { createFileRoute } from '@tanstack/react-router'; import { source } from '@/lib/source'; import { getLLMText } from '@/lib/get-llm-text'; export const Route = createFileRoute('/llms-full.txt')({ server: { handlers: { GET: async () => { const scan = source.getPages().map(getLLMText); const scanned = await Promise.all(scan); return new Response(scanned.join('\n\n')); }, }, }, }); ``` *.mdx [#mdx-extension] Allow AI agents to get the content of a page as Markdown/MDX, by appending `.mdx` to the end of path. Make a route handler to return page content, and a middleware to point to it: Next.js React Router Tanstack Start ```ts title="app/llms.mdx/docs/[[...slug]]/route.ts" import { getLLMText } from '@/lib/get-llm-text'; import { source } from '@/lib/source'; import { notFound } from 'next/navigation'; export const revalidate = false; export async function GET(_req: Request, { params }: RouteContext<'/llms.mdx/docs/[[...slug]]'>) { const { slug } = await params; const page = source.getPage(slug); if (!page) notFound(); return new Response(await getLLMText(page), { headers: { 'Content-Type': 'text/markdown', }, }); } export function generateStaticParams() { return source.generateParams(); } ``` ```ts title="next.config.ts" import type { NextConfig } from 'next'; const config: NextConfig = { // [!code ++:8] async rewrites() { return [ { source: '/docs/:path*.mdx', destination: '/llms.mdx/docs/:path*', }, ]; }, }; ``` ```ts title="app/routes.ts" import { index, route, type RouteConfig } from '@react-router/dev/routes'; export default [ // [!code ++] route('llms.mdx/docs/*', 'routes/docs/llms-mdx.ts'), ] satisfies RouteConfig; ``` ```ts title="app/routes/docs/llms-mdx.ts" import type { Route } from './+types/llms-mdx'; import { source } from '@/lib/source'; import { getLLMText } from '@/lib/get-llm-text'; export async function loader({ params }: Route.LoaderArgs) { const slugs = params['*'].split('/').filter((v) => v.length > 0); const page = source.getPage(slugs); if (!page) { return new Response('not found', { status: 404 }); } return new Response(await getLLMText(page), { headers: { 'Content-Type': 'text/markdown', }, }); } ``` ```ts title="app/root.tsx" import { rewritePath } from 'fumadocs-core/negotiation'; import type { Route } from './+types/root'; // [!code ++:20] const { rewrite: rewriteLLM } = rewritePath('/docs{/*path}.mdx', '/llms.mdx/docs{/*path}'); const serverMiddleware: Route.MiddlewareFunction = async ({ request }, next) => { const url = new URL(request.url); const path = rewriteLLM(url.pathname); if (path) return Response.redirect(new URL(path, url)); return next(); }; export const middleware = [serverMiddleware]; ``` ```ts title="src/routes/llms[.]mdx.docs.$.ts" import { createFileRoute, notFound } from '@tanstack/react-router'; import { source } from '@/lib/source'; export const Route = createFileRoute('/llms.mdx/docs/$')({ server: { handlers: { GET: async ({ params }) => { const slugs = params._splat?.split('/') ?? []; const page = source.getPage(slugs); if (!page) throw notFound(); return new Response(await page.data.getText('raw'), { headers: { 'Content-Type': 'text/markdown', }, }); }, }, }, }); ``` ```ts title="src/start.ts" import { createMiddleware, createStart } from '@tanstack/react-start'; import { rewritePath } from 'fumadocs-core/negotiation'; import { redirect } from '@tanstack/react-router'; const { rewrite: rewriteLLM } = rewritePath('/docs{/*path}.mdx', 'llms.mdx/docs{/*path}'); const llmMiddleware = createMiddleware().server(({ next, request }) => { const url = new URL(request.url); const path = rewriteLLM(url.pathname); if (path) { throw redirect(new URL(path, url)); } return next(); }); export const startInstance = createStart(() => { return { requestMiddleware: [llmMiddleware], }; }); ``` Accept [#accept] To serve the Markdown content instead for AI agents, you can leverage the `Accept` header. ```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/docs{/*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(); } ``` Page Actions [#page-actions] Common page actions for AI, require [`*.mdx`](#mdx-extension) to be implemented first. AI Page Actions

npm pnpm yarn bun ```bash npx @fumadocs/cli add ai/page-actions ``` ```bash pnpm dlx @fumadocs/cli add ai/page-actions ``` ```bash yarn dlx @fumadocs/cli add ai/page-actions ``` ```bash bun x @fumadocs/cli add ai/page-actions ``` Use it in your docs page like: ```tsx title="app/docs/[[...slug]]/page.tsx"

``` Ask AI [#ask-ai]

You can install the AI search dialog using Fumadocs CLI: npm pnpm yarn bun ```bash npx @fumadocs/cli add ai/search ``` ```bash pnpm dlx @fumadocs/cli add ai/search ``` ```bash yarn dlx @fumadocs/cli add ai/search ``` ```bash bun x @fumadocs/cli add ai/search ``` By default, it's configured for [Inkeep AI](https://inkeep.com) using Vercel AI SDK. To setup for Inkeep AI: 1. Add your Inkeep API key to environment variables: ```dotenv INKEEP_API_KEY="..." ``` 2. Add the component & trigger to root layout (or anywhere you prefer): ```tsx import { AISearch, AISearchPanel, AISearchTrigger } from '@/components/ai/search'; import { MessageCircleIcon } from 'lucide-react'; import { buttonVariants } from '@/components/button'; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {/* [!code ++:17] */} Ask AI {children} ); } ``` To use your own AI models, update the configurations in `useChat` and `/api/chat` route. Note that Fumadocs doesn't provide the AI model, it's up to you. Your AI model can use the `llms-full.txt` file generated above, or more diversified sources of information when combined with 3rd party solutions. # Fumadocs (Framework Mode): Validate Links URL: /docs/integrations/validate-links Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/integrations/validate-links.mdx Ensure your links are correct. Setup [#setup] You can use [`next-validate-link`](https://next-validate-link.vercel.app) to validate your links in content files. > > This guide is mainly for **Fumadocs MDX**, see the docs of `next-validate-link` for other setups. > Create a script: ```ts title="scripts/lint.ts" import { type FileObject, printErrors, scanURLs, validateFiles } from 'next-validate-link'; import type { InferPageType } from 'fumadocs-core/source'; import { source } from '@/lib/source'; async function checkLinks() { const scanned = await scanURLs({ // pick a preset for your React framework preset: 'next', populate: { 'docs/[[...slug]]': source.getPages().map((page) => { return { value: { slug: page.slugs, }, hashes: getHeadings(page), }; }), }, }); printErrors( await validateFiles(await getFiles(), { scanned, // check `href` attributes in different MDX components markdown: { components: { Card: { attributes: ['href'] }, }, }, // check relative paths checkRelativePaths: 'as-url', }), true, ); } function getHeadings({ data }: InferPageType): string[] { return data.toc.map((item) => item.url.slice(1)); } function getFiles() { const promises = source.getPages().map( async (page): Promise => ({ path: page.absolutePath, content: await page.data.getText('raw'), url: page.url, data: page.data, }), ); return Promise.all(promises); } void checkLinks(); ``` Running Lint [#running-lint] To access the `source` object outside of app runtime, configure [Fumadocs MDX Loader](/docs/mdx/loader/bun) first. Then, run the script to validate links: ```bash bun ./scripts/lint.ts ``` > > For Node.js, you might need to configure `tsconfig-paths`, TypeScript transpiling, and [Fumadocs MDX Loader](/docs/mdx/loader/node). > > > > Without special reasons, using Bun or [`tsx`](https://github.com/privatenumber/tsx) would be simpler. > # Fumadocs (Framework Mode): Internationalization URL: /docs/internationalization Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/internationalization/index.mdx Support multiple languages in your documentation Overview [#overview] You'll have to configure i18n routing on your React framework and Fumadocs. Fumadocs is not a full-powered i18n library, it's up to you when internationalizing the rest of your app. You can also use other libraries with Fumadocs like [next-intl](https://github.com/amannn/next-intl) on Next.js. # Fumadocs (Framework Mode): Next.js URL: /docs/internationalization/next Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/internationalization/next.mdx Support i18n routing on your Next.js + Fumadocs app You can [learn more about i18n in Next.js](https://nextjs.org/docs/app/building-your-application/routing/internationalization). Setup [#setup] Define the i18n configurations in a file, we will import it with `@/lib/i18n` in this guide. ```ts title="lib/i18n.ts" import { defineI18n } from 'fumadocs-core/i18n'; export const i18n = defineI18n({ defaultLanguage: 'en', languages: ['en', 'cn'], }); ``` > > See [available options](/docs/headless/internationalization) for i18n config. > Middleware [#middleware] 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#hide-locale-prefix) option you set in your i18n config. Routing [#routing] 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! Provide UI translations and other config to ``, the English translations are used when `translations` is not specified. ```tsx title="app/[lang]/layout.tsx" import { RootProvider } from 'fumadocs-ui/provider/next'; import { defineI18nUI } from 'fumadocs-ui/i18n'; import { i18n } from '@/lib/i18n'; // [!code ++:11] const { provider } = defineI18nUI(i18n, { translations: { en: { displayName: 'English', }, cn: { displayName: 'Chinese', search: '搜尋文檔', }, }, }); export default async function RootLayout({ params, children, }: { params: Promise<{ lang: string }>; children: React.ReactNode; }) { const lang = (await params).lang; return ( {children} ); } ``` Pass Locale [#pass-locale] Add `locale` parameter to `baseOptions()` and add `i18n` into it: ```tsx title="lib/layout.shared.tsx" import { i18n } from '@/lib/i18n'; import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; // [!code highlight] export function baseOptions(locale: string): BaseLayoutProps { return { i18n, // [!code ++] // different props based on `locale` }; } ``` 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 ++] } ``` Using another name for lang dynamic segment?}> If you're using another name like `app/[locale]`, you also need to update `generateStaticParams()` in docs page: ```tsx export function generateStaticParams() { return source.generateParams(); // [!code --] return source.generateParams('slug', 'locale'); // [!code ++] new param name } ``` Search [#search] 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. Writing Documents [#writing-documents] See [i18n routing](/docs/page-conventions#i18n-routing) to learn how to create pages for specific locales. Navigation [#navigation] Fumadocs only handles navigation for its own layouts (e.g. sidebar). For other places, you can use the `useParams` hook to get the locale from url, and prepend it to `href`. ```tsx import Link from 'next/link'; import { useParams } from 'next/navigation'; const { lang } = useParams(); return This is a link; ``` In addition, the [`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) component supports dynamic hrefs, you can use it to prepend the locale prefix. It is useful for Markdown/MDX content. ```mdx title="content.mdx" import { DynamicLink } from 'fumadocs-core/dynamic-link'; This is a link ``` # Fumadocs (Framework Mode): React Router URL: /docs/internationalization/react-router Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/internationalization/react-router.mdx Support i18n routing on your React Router + Fumadocs app. Setup [#setup] Define the i18n configurations in a file, we will import it with `@/lib/i18n` in this guide. ```ts title="app/lib/i18n.ts" import { defineI18n } from 'fumadocs-core/i18n'; export const i18n = defineI18n({ defaultLanguage: 'en', languages: ['cn', 'en'], }); ``` > > See [available options](/docs/headless/internationalization) for i18n config. > Routing [#routing] Add `:lang` prefix to all your pages. ```ts title="app/routes.ts" import { route, type RouteConfig } from '@react-router/dev/routes'; export default [ // [!code highlight:2] route(':lang', 'routes/home.tsx'), route(':lang/docs/*', 'docs/page.tsx'), route('api/search', 'docs/search.ts'), ] satisfies RouteConfig; ``` Make locale optional [#make-locale-optional] You can also use `:lang?` prefix, and update the i18n config: app/lib/i18n.ts app/routes.ts ```ts import { defineI18n } from 'fumadocs-core/i18n'; export const i18n = defineI18n({ defaultLanguage: 'en', languages: ['cn', 'en'], // [!code ++] hideLocale: 'default-locale', }); ``` ```ts import { route, type RouteConfig } from '@react-router/dev/routes'; export default [ // [!code highlight:2] route(':lang?', 'routes/home.tsx'), route(':lang?/docs/*', 'docs/page.tsx'), route('api/search', 'docs/search.ts'), ] satisfies RouteConfig; ``` Pages [#pages] Provide UI translations and other config to ``, the English translations are used as fallbacks. ```tsx title="app/root.tsx" import { Links, Meta, Scripts, ScrollRestoration, useParams } from 'react-router'; import { RootProvider } from 'fumadocs-ui/provider/base'; import { ReactRouterProvider } from 'fumadocs-core/framework/react-router'; import { defineI18nUI } from 'fumadocs-ui/i18n'; import { i18n } from '@/lib/i18n'; import './app.css'; // [!code ++:11] const { provider } = defineI18nUI(i18n, { translations: { en: { displayName: 'English', }, cn: { displayName: 'Chinese', search: '搜尋文檔', }, }, }); export function Layout({ children }: { children: React.ReactNode }) { const { lang = i18n.defaultLanguage } = useParams(); return ( {children} ); } ``` Pass Locale [#pass-locale] Add `locale` parameter to `baseOptions()` and include `i18n` in props: ```tsx title="app/lib/layout.shared.tsx" import { i18n } from '@/lib/i18n'; import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export function baseOptions(locale: string): BaseLayoutProps { return { i18n, // [!code ++] // different props based on `locale` }; } ``` Pass the locale to Fumadocs in your pages and layouts. app/lib/source.ts Home 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/routes/home.tsx" import type { Route } from './+types/home'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { baseOptions } from '@/lib/layout.shared'; export default function Home({ params }: Route.ComponentProps) { return ( // [!code highlight] ); } ``` ```tsx title="app/docs/page.tsx" import type { Route } from './+types/page'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { source } from '@/lib/source'; import type * as PageTree from 'fumadocs-core/page-tree'; import { baseOptions } from '@/lib/layout.shared'; export async function loader({ params }: Route.LoaderArgs) { const slugs = params['*'].split('/').filter((v) => v.length > 0); // [!code --] const page = source.getPage(slugs); // [!code ++] const page = source.getPage(slugs, params.lang); if (!page) throw new Response('Not found', { status: 404 }); return { path: page.path, // [!code --] tree: source.getPageTree(), // [!code ++] tree: source.getPageTree(params.lang), }; } export default function Page({ loaderData, params }: Route.ComponentProps) { const { tree, path } = loaderData; return ( ); } ``` Search [#search] 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. Writing Documents [#writing-documents] See [i18n routing](/docs/page-conventions#i18n-routing) to learn how to create pages for specific locales. Navigation [#navigation] Fumadocs only handles navigation for its own layouts (e.g. sidebar). For other places, you can use the `useParams` hook to get the locale from url. ```tsx import { Link, useParams } from 'react-router'; const { lang } = useParams(); About Us; ``` In addition, the [`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) component supports dynamic hrefs, you can use it to attend the locale prefix. It is useful for Markdown/MDX content. ```mdx title="content.mdx" import { DynamicLink } from 'fumadocs-core/dynamic-link'; This is a link ``` # Fumadocs (Framework Mode): Tanstack Start URL: /docs/internationalization/tanstack-start Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/internationalization/tanstack-start.mdx Support i18n routing on your Tanstack Start + Fumadocs app. Setup [#setup] Define the i18n configurations in a file, we will import it with `@/lib/i18n` in this guide. ```ts title="src/lib/i18n.ts" import { defineI18n } from 'fumadocs-core/i18n'; export const i18n = defineI18n({ defaultLanguage: 'en', languages: ['cn', 'en'], }); ``` > > See [available options](/docs/headless/internationalization) for i18n config. > Routing [#routing] Create a `$lang` directory under `routes`, and move all pages into it. Provide UI translations and other config to ``, the English translations are used as fallbacks. ```tsx title="src/routes/__root.tsx" import { HeadContent, Scripts, useParams } from '@tanstack/react-router'; import * as React from 'react'; import { RootProvider } from 'fumadocs-ui/provider/base'; import { TanstackProvider } from 'fumadocs-core/framework/tanstack'; import { defineI18nUI } from 'fumadocs-ui/i18n'; import { i18n } from '@/lib/i18n'; // [!code ++:11] const { provider } = defineI18nUI(i18n, { translations: { cn: { displayName: 'Chinese', search: 'Translated Content', }, en: { displayName: 'English', }, }, }); function RootDocument({ children }: { children: React.ReactNode }) { const { lang } = useParams({ strict: false }); return ( {children} ); } ``` Pass Locale [#pass-locale] Add `locale` parameter to `baseOptions()` and include `i18n` in props: ```tsx title="src/lib/layout.shared.tsx" import { i18n } from '@/lib/i18n'; import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export function baseOptions(locale: string): BaseLayoutProps { return { i18n, // [!code ++] // different props based on `locale` }; } ``` Pass the locale to Fumadocs in your pages and layouts. src/lib/source.ts Home 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="src/routes/$lang/index.tsx" import { createFileRoute } from '@tanstack/react-router'; import { HomeLayout } from 'fumadocs-ui/layouts/home'; import { baseOptions } from '@/lib/layout.shared'; export const Route = createFileRoute('/$lang/')({ component: Home, }); function Home() { const { lang } = Route.useParams(); // [!code highlight] return ; } ``` ```tsx title="src/routes/$lang/docs/$.tsx" import { createFileRoute, notFound } from '@tanstack/react-router'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { createServerFn } from '@tanstack/react-start'; import { source } from '@/lib/source'; import { baseOptions } from '@/lib/layout.shared'; export const Route = createFileRoute('/$lang/docs/$')({ component: Page, loader: async ({ params }) => { const data = await loader({ // [!code ++:4] data: { slugs: params._splat?.split('/') ?? [], lang: params.lang, }, }); await clientLoader.preload(data.path); return data; }, }); // [!code highlight:13] const loader = createServerFn({ method: 'GET', }) .inputValidator((params: { slugs: string[]; lang?: string }) => params) .handler(async ({ data: { slugs, lang } }) => { const page = source.getPage(slugs, lang); if (!page) throw notFound(); return { tree: source.getPageTree(lang) as object, path: page.path, }; }); function Page() { const { lang } = Route.useParams(); // ... return ( // [!code highlight] ); } ``` Search [#search] 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. Writing Documents [#writing-documents] See [i18n routing](/docs/page-conventions#i18n-routing) to learn how to create pages for specific locales. Navigation [#navigation] Fumadocs only handles navigation for its own layouts (e.g. sidebar). For other places, you can use the `useParams` hook to get the locale from url. ```tsx import { Link, useParams } from '@tanstack/react-router'; const { lang } = useParams({ from: '/$lang/' }); Open Docs ; ``` In addition, the [`fumadocs-core/dynamic-link`](/docs/headless/components/link#dynamic-hrefs) component supports dynamic hrefs, you can use it to attend the locale prefix. It is useful for Markdown/MDX content. ```mdx title="content.mdx" import { DynamicLink } from 'fumadocs-core/dynamic-link'; This is a link ``` # Fumadocs (Framework Mode): Manual Installation URL: /docs/manual-installation Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/manual-installation/index.mdx Add Fumadocs to existing projects. # Fumadocs (Framework Mode): Next.js URL: /docs/manual-installation/next Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/manual-installation/next.mdx Setup Fumadocs on Next.js. Prerequisite [#prerequisite] Before continuing, make sure you have configured: * Next.js 16. * Tailwind CSS 4. We will use [Fumadocs MDX](/docs/mdx) as a content source, you can configure it first:

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 ++] "fumadocs-mdx: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 'fumadocs-mdx: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.

Fumadocs also supports other content sources, including [Content Collections](/docs/headless/content-collections) and headless CMS. Getting Started [#getting-started] npm pnpm yarn bun ```bash npm i fumadocs-ui fumadocs-core ``` ```bash pnpm add fumadocs-ui fumadocs-core ``` ```bash yarn add fumadocs-ui fumadocs-core ``` ```bash bun add fumadocs-ui fumadocs-core ``` Root Layout [#root-layout] Wrap the entire application inside [Root Provider](/docs/ui/layouts/root-provider), and add required styles to `body`. ```tsx title="app/layout.tsx" import { RootProvider } from 'fumadocs-ui/provider/next'; import type { ReactNode } from 'react'; export default function Layout({ children }: { children: ReactNode }) { return ( {children} ); } ``` Styles [#styles] Add the following Tailwind CSS styles to `global.css`. ```css title="global.css" @import 'tailwindcss'; /* [!code ++:2] */ @import 'fumadocs-ui/css/neutral.css'; @import 'fumadocs-ui/css/preset.css'; ``` > > It doesn't come with a default font, you may choose one from `next/font`. > Routes [#routes] Create a `lib/layout.shared.tsx` file to put the shared options for our layouts. ```tsx title="lib/layout.shared.tsx" import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export function baseOptions(): BaseLayoutProps { return { nav: { title: 'My App', }, }; } ``` Create the following files & routes: mdx-components.tsx app/docs/layout.tsx app/docs/[[...slug]]/page.tsx app/api/search/route.ts ```tsx import defaultMdxComponents from 'fumadocs-ui/mdx'; import type { MDXComponents } from 'mdx/types'; export function getMDXComponents(components?: MDXComponents): MDXComponents { return { ...defaultMdxComponents, ...components, }; } ``` ```tsx import { source } from '@/lib/source'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { baseOptions } from '@/lib/layout.shared'; export default function Layout({ children }: LayoutProps<'/docs'>) { return ( {children} ); } ``` ```tsx import { source } from '@/lib/source'; import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page'; import { notFound } from 'next/navigation'; import { getMDXComponents } from '@/mdx-components'; import type { Metadata } from 'next'; import { createRelativeLink } from 'fumadocs-ui/mdx'; export default async function Page(props: PageProps<'/docs/[[...slug]]'>) { const params = await props.params; const page = source.getPage(params.slug); if (!page) notFound(); const MDX = page.data.body; return ( {page.data.title} {page.data.description} ); } export async function generateStaticParams() { return source.generateParams(); } export async function generateMetadata(props: PageProps<'/docs/[[...slug]]'>): Promise { const params = await props.params; const page = source.getPage(params.slug); if (!page) notFound(); return { title: page.data.title, description: page.data.description, }; } ``` ```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', }); ``` > > The search is powered by Orama, learn more about [Document Search](/docs/headless/search). > Finish [#finish] You can start the dev server and create MDX files. ```mdx title="content/docs/index.mdx" --- title: Hello World --- ## Introduction I love Anime. ``` # Fumadocs (Framework Mode): React Router URL: /docs/manual-installation/react-router Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/manual-installation/react-router.mdx Setup Fumadocs on React Router. Getting Started [#getting-started] Before continuing, make sure to configure: * Tailwind CSS 4. * Fumadocs MDX: follow the [Vite setup guide](/docs/mdx/vite) and create essential files like `lib/source.ts`. Installation [#installation] npm pnpm yarn bun ```bash npm i fumadocs-core fumadocs-ui ``` ```bash pnpm add fumadocs-core fumadocs-ui ``` ```bash yarn add fumadocs-core fumadocs-ui ``` ```bash bun add fumadocs-core fumadocs-ui ``` Styles [#styles] Add the following to your Tailwind CSS file: ```css title="app/app.css" @import 'tailwindcss'; /* [!code ++:2] */ @import 'fumadocs-ui/css/neutral.css'; @import 'fumadocs-ui/css/preset.css'; ``` Create Pages [#create-pages] Update your routes: ```ts title="routes.ts" import { type RouteConfig, index, route } from '@react-router/dev/routes'; export default [ index('routes/home.tsx'), // [!code ++:2] route('docs/*', 'docs/page.tsx'), route('api/search', 'docs/search.ts'), ] satisfies RouteConfig; ``` Create the following files: app/lib/layout.shared.tsx app/docs/page.tsx app/docs/search.ts ```tsx import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export function baseOptions(): BaseLayoutProps { return { nav: { title: 'React Router', }, }; } ``` ```tsx import type { Route } from './+types/page'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page'; import { source } from '@/lib/source'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import browserCollections from 'fumadocs-mdx:collections/browser'; import { baseOptions } from '@/lib/layout.shared'; import { useFumadocsLoader } from 'fumadocs-core/source/client'; export async function loader({ params }: Route.LoaderArgs) { const slugs = params['*'].split('/').filter((v) => v.length > 0); const page = source.getPage(slugs); if (!page) throw new Response('Not found', { status: 404 }); return { path: page.path, pageTree: await source.serializePageTree(source.getPageTree()), }; } const clientLoader = browserCollections.docs.createClientLoader({ component( { toc, frontmatter, default: Mdx }, // you can define props for the `` component props?: { className?: string; }, ) { return ( {frontmatter.title} {frontmatter.title} {frontmatter.description} ); }, }); export default function Page({ loaderData }: Route.ComponentProps) { const { path, pageTree } = useFumadocsLoader(loaderData); return ( {clientLoader.useContent(path)} ); } ``` ```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); } ``` Wrap your entire app under Fumadocs providers: ```tsx title="root.tsx" import { Links, Meta, Scripts, ScrollRestoration } from 'react-router'; import { RootProvider } from 'fumadocs-ui/provider/react-router'; import './app.css'; export function Layout({ children }: { children: React.ReactNode }) { return ( {/* [!code ++] */} {children} ); } ``` Done [#done] You can start writing documents at `content/docs`: ```mdx title="content/docs/index.mdx" --- title: Hello World --- I love Fumadocs ``` # Fumadocs (Framework Mode): Tanstack Start URL: /docs/manual-installation/tanstack-start Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/manual-installation/tanstack-start.mdx Setup Fumadocs on Tanstack Start. Getting Started [#getting-started] Before continuing, make sure to configure: * Tailwind CSS 4. * Fumadocs MDX: follow the [Vite setup guide](/docs/mdx/vite) and create essential files like `lib/source.ts`. Installation [#installation] npm pnpm yarn bun ```bash npm i fumadocs-core fumadocs-ui ``` ```bash pnpm add fumadocs-core fumadocs-ui ``` ```bash yarn add fumadocs-core fumadocs-ui ``` ```bash bun add fumadocs-core fumadocs-ui ``` Styles [#styles] Add the following to your Tailwind CSS file: ```css title="styles/app.css" @import 'tailwindcss'; /* [!code ++:2] */ @import 'fumadocs-ui/css/neutral.css'; @import 'fumadocs-ui/css/preset.css'; ``` Create Pages [#create-pages] Create the following routes: lib/layout.shared.tsx routes/docs/$.tsx routes/api/search.ts ```tsx import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export function baseOptions(): BaseLayoutProps { return { nav: { title: 'Tanstack Start', }, }; } ``` ```tsx import { createFileRoute, notFound } from '@tanstack/react-router'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { createServerFn } from '@tanstack/react-start'; import { source } from '@/lib/source'; import browserCollections from 'fumadocs-mdx:collections/browser'; import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { baseOptions } from '@/lib/layout.shared'; import { useFumadocsLoader } from 'fumadocs-core/source/client'; import { Suspense } from 'react'; export const Route = createFileRoute('/docs/$')({ component: Page, loader: async ({ params }) => { const slugs = params._splat?.split('/') ?? []; const data = await serverLoader({ data: slugs }); await clientLoader.preload(data.path); return data; }, }); const serverLoader = createServerFn({ method: 'GET', }) .inputValidator((slugs: string[]) => slugs) .handler(async ({ data: slugs }) => { const page = source.getPage(slugs); if (!page) throw notFound(); return { path: page.path, pageTree: await source.serializePageTree(source.getPageTree()), }; }); const clientLoader = browserCollections.docs.createClientLoader({ component( { toc, frontmatter, default: MDX }, // you can define props for the component props: { className?: string; }, ) { return ( {frontmatter.title} {frontmatter.description} ); }, }); function Page() { const data = useFumadocsLoader(Route.useLoaderData()); return ( {clientLoader.useContent(data.path, { className: '', })} ); } ``` ```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), }, }, }); ``` Wrap your entire app under Fumadocs providers: ```tsx title="__root.tsx" import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router'; import * as React from 'react'; import { RootProvider } from 'fumadocs-ui/provider/tanstack'; export const Route = createRootRoute({ component: RootComponent, }); function RootComponent() { return ( ); } function RootDocument({ children }: { children: React.ReactNode }) { return ( {/* [!code ++] */} {children} ); } ``` Done [#done] You can start writing documents at `content/docs`: ```mdx title="content/docs/index.mdx" --- title: Hello World --- I love Fumadocs ``` # Fumadocs (Framework Mode): Waku URL: /docs/manual-installation/waku Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/manual-installation/waku.mdx Setup Fumadocs on Waku. Getting Started [#getting-started] Before continuing, make sure to configure: * Tailwind CSS 4. * Fumadocs MDX: follow the [Vite setup guide](/docs/mdx/vite) and create essential files like `lib/source.ts`. Installation [#installation] npm pnpm yarn bun ```bash npm i fumadocs-core fumadocs-ui ``` ```bash pnpm add fumadocs-core fumadocs-ui ``` ```bash yarn add fumadocs-core fumadocs-ui ``` ```bash bun add fumadocs-core fumadocs-ui ``` Styles [#styles] Add the following to your Tailwind CSS file: ```css title="src/styles/globals.css" @import 'tailwindcss'; /* [!code ++:2] */ @import 'fumadocs-ui/css/neutral.css'; @import 'fumadocs-ui/css/preset.css'; ``` Create Pages [#create-pages] Create a file for sharing layout props: ```tsx title="src/lib/layout.shared.tsx" import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared'; export function baseOptions(): BaseLayoutProps { return { nav: { title: 'Waku', }, }; } ``` Create the following routes: src/pages/docs/_layout.tsx src/pages/docs/[...slugs].tsx src/pages/api/search.ts ```tsx import type { ReactNode } from 'react'; import { DocsLayout } from 'fumadocs-ui/layouts/docs'; import { source } from '@/lib/source'; import { baseOptions } from '@/lib/layout.shared'; export default function Layout({ children }: { children: ReactNode }) { return ( {children} ); } ``` ```tsx import { source } from '@/lib/source'; import { PageProps } from 'waku/router'; import defaultMdxComponents from 'fumadocs-ui/mdx'; import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page'; export default function DocPage({ slugs }: PageProps<'/docs/[...slugs]'>) { const page = source.getPage(slugs); if (!page) { return (

Page Not Found

The page you are looking for does not exist.

); } const MDX = page.data.body; return ( {page.data.title} {page.data.description} ); } export async function getConfig() { const pages = source .generateParams() .map((item) => (item.lang ? [item.lang, ...item.slug] : item.slug)); return { render: 'static' as const, staticPaths: pages, } as const; } ``` ```ts import { createFromSource } from 'fumadocs-core/search/server'; import { source } from '@/lib/source'; export const { GET } = createFromSource(source); ``` Finally, wrap your entire app under Fumadocs providers: src/components/provider.tsx src/pages/_layout.tsx ```tsx 'use client'; import type { ReactNode } from 'react'; import { RootProvider } from 'fumadocs-ui/provider/waku'; export function Provider({ children }: { children: ReactNode }) { return {children}; } ``` ```tsx import '@/styles/globals.css'; import type { ReactNode } from 'react'; import { Provider } from '@/components/provider'; // [!code ++:3] export default function RootLayout({ children }: { children: ReactNode }) { return {children}; } export const getConfig = async () => { return { render: 'static', }; }; ``` Done [#done] You can start writing documents at `content/docs`: ```mdx title="content/docs/index.mdx" --- title: Hello World --- I love Fumadocs ``` # Fumadocs (Framework Mode): Markdown URL: /docs/markdown Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/markdown/index.mdx How to write documents Introduction [#introduction] Fumadocs provides many useful extensions to MDX, a markup language. Here is a brief introduction to the default MDX syntax of Fumadocs. > > MDX is not the only supported format of Fumadocs. In fact, you can use any renderer such as headless CMS. > > > > See [Custom Content Source](/docs/integrations/content/custom) for details. > MDX [#mdx] We recommend MDX, a superset of Markdown with JSX syntax. It allows you to import components, and use them in the document, or even writing JavaScript. See: * [MDX Syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax). * GFM (GitHub Flavored Markdown) is also supported, see [GFM Specification](https://github.github.com/gfm). ```mdx import { Component } from './component'; ## Heading ### Heading #### Heading Hello World, **Bold**, _Italic_, ~~Hidden~~ 1. First 2. Second 3. Third - Item 1 - Item 2 > Quote here ![alt](/image.png) | Table | Description | | ----- | ----------- | | Hello | World | ``` Frontmatter [#frontmatter] Fumadocs support YAML-based frontmatter by default, `title` represents the page title (`h1`) in Fumadocs UI. ```mdx --- title: This is a document --- ... ``` For this reason, h1 title (`# Heading`) is usually unused when writing Markdown/MDX unless you have custom logic for page title rendering. You can use the [`schema`](/docs/mdx/collections#schema-1) option to add frontmatter properties. Auto Links [#auto-links] Internal links use the `` component of your React framework (e.g. `next/link`) to allow prefetching and avoid hard-reload. External links will get the default `rel="noreferrer noopener" target="_blank"` attributes for security. ```mdx [My Link](https://github.github.com/gfm) This also works: https://github.github.com/gfm. ``` Cards [#cards] Useful for adding links. ```mdx import { HomeIcon } from 'lucide-react'; Learn more about caching in Next.js Learn more about `fetch` in Next.js. } href="/" title="Home"> You can include icons too. ``` Learn more about caching in Next.js Learn more about `fetch` in Next.js. } href="/" title="Home"> You can include icons too. "Further Reading" Section [#further-reading-section] You can do something like: ```tsx title="page.tsx" import { getPageTreePeers } from 'fumadocs-core/page-tree'; import { source } from '@/lib/source'; {getPageTreePeers(source.getPageTree(), '/docs/my-page').map((peer) => ( {peer.description} ))} ; ``` This will show the other pages in the same folder as cards. Callouts [#callouts] Useful for adding tips/warnings, it is included by default. You can specify the type of callout: * `info` (default) * `warn`/`warning` * `error` * `success` * `idea` ```mdx Hello World Hello World Hello World Hello World ``` Hello World Hello World Hello World Hello World Headings [#headings] An anchor is automatically applied to each heading, it sanitizes invalid characters like spaces. (e.g. `Hello World` to `hello-world`) ```md # Hello `World` ``` TOC Settings [#toc-settings] The table of contents (TOC) will be generated based on headings, you can also customise the effects of headings: ```md # Heading [!toc] This heading will be hidden from TOC. # Another Heading [toc] This heading will **only** be visible in TOC, you can use it to add additional TOC items. Like headings rendered in a React component: ``` Custom Anchor [#custom-anchor] You can add `[#slug]` to customise heading anchors. ```md # heading [#my-heading-id] ``` You can also chain it with TOC settings like: ```md # heading [toc] [#my-heading-id] ``` To link people to a specific heading, add the heading id to hash fragment: `/page#my-heading-id`. Codeblock [#codeblock] Syntax Highlighting is supported by default using [Rehype Code](/docs/headless/mdx/rehype-code). ````mdx ```js console.log('Hello World'); ``` ```js title="My Title" console.log('Hello World'); ``` ```` Line Numbers [#line-numbers] Show line numbers, it also works with Twoslash and other transformers. Input Output ````mdx ```ts twoslash lineNumbers const a = 'Hello World'; // ^? console.log(a); // [!code highlight] ``` ```` ```ts twoslash lineNumbers const a = 'Hello World'; // ^? console.log(a); // [!code highlight] ``` You can set the initial value of line numbers. Input Output ````mdx ```js lineNumbers=4 function main() { console.log('starts from 4'); return 0; } ``` ```` ```js lineNumbers=4 function main() { console.log('starts from 4'); return 0; } ``` Shiki Transformers [#shiki-transformers] We support some of the [Shiki Transformers](https://shiki.style/packages/transformers), allowing you to highlight/style specific lines. Input Output ````md ```tsx // highlight a line

Hello World

// [\!code highlight] // highlight a word // [\!code word:Fumadocs]

Fumadocs

// diff styles console.log('hewwo'); // [\!code --] console.log('hello'); // [\!code ++] // focus return new ResizeObserver(() => {}) // [\!code focus] ``` ```` ```tsx // highlight a line

Hello World

// [!code highlight] // highlight a word // [!code word:Fumadocs]

Fumadocs

// diff styles: console.log('hewwo'); // [!code --] console.log('hello'); // [!code ++] // focus return new ResizeObserver(() => {}) // [!code focus] ``` Tab Groups [#tab-groups] ````mdx ```ts tab="Tab 1" console.log('A'); ``` ```ts tab="Tab 2" console.log('B'); ``` ```` Tab 1 Tab 2 ```ts console.log('A'); ``` ```ts console.log('B'); ``` While disabled by default, you use MDX in tab values by configuring the remark plugin: Fumadocs MDX MDX Compiler ```ts title="source.config.ts" import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { remarkCodeTabOptions: { parseMdx: true, // [!code ++] }, }, }); ``` ```ts import { compile } from '@mdx-js/mdx'; import { remarkCodeTab } from 'fumadocs-core/mdx-plugins'; await compile('...', { remarkPlugins: [ [ remarkCodeTab, { parseMdx: true, // [!code ++] }, ], ], }); ``` ````mdx ```ts tab=" Tab 1" console.log('A'); ``` ```ts tab=" Tab 2" console.log('B'); ``` ```` Tab 1 Tab 2 ```ts console.log('A'); ``` ```ts console.log('B'); ``` Include [#include] > > This is only available on **Fumadocs MDX**. > Reference another file (can also be a Markdown/MDX document). Specify the target file path in `` tag (relative to the MDX file itself). ```mdx title="page.mdx" ./another.mdx ``` See [other usages of include](/docs/mdx/include). NPM Commands [#npm-commands] Useful for generating commands for installing packages with different package managers. Input Output ````md ```npm npm i next -D ``` ```` npm pnpm yarn bun ```bash npm i next -D ``` ```bash pnpm add next -D ``` ```bash yarn add next --dev ``` ```bash bun add next --dev ``` See [`remark-npm`](/docs/headless/mdx/remark-npm) for details. Other Components [#other-components] You can configure & use the [built-in components](/docs/ui/components) in your MDX document, such as Tabs, Accordions and Zoomable Image. Additional Features [#additional-features] You may be interested: # Fumadocs (Framework Mode): Math URL: /docs/markdown/math Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/markdown/math.mdx Writing math equations in Markdown/MDX. Getting Started [#getting-started] npm pnpm yarn bun ```bash npm install remark-math rehype-katex katex ``` ```bash pnpm add remark-math rehype-katex katex ``` ```bash yarn add remark-math rehype-katex katex ``` ```bash bun add remark-math rehype-katex katex ``` Add Plugins [#add-plugins] Add the required remark/rehype plugins, the code might be vary depending on your content source. Fumadocs MDX ```ts title="source.config.ts" import rehypeKatex from 'rehype-katex'; import remarkMath from 'remark-math'; import { defineConfig } from 'fumadocs-mdx/config'; export default defineConfig({ mdxOptions: { remarkPlugins: [remarkMath], // Place it at first, it should be executed before the syntax highlighter rehypePlugins: (v) => [rehypeKatex, ...v], }, }); ``` Add Stylesheet [#add-stylesheet] Add the following to root layout to make it looks great: ```tsx title="layout.tsx" import 'katex/dist/katex.css'; ``` Done [#done] Type some TeX expression in your documents, like the Pythagoras theorem: ````mdx Inline: $$c = \pm\sqrt{a^2 + b^2}$$ ```math c = \pm\sqrt{a^2 + b^2} ``` ```` Inline: $c = \pm\sqrt{a^2 + b^2}$ ```math c = \pm\sqrt{a^2 + b^2} ``` Taylor Expansion (expressing holomorphic function $f(x)$ in power series): ```math \displaystyle {\begin{aligned}T_{f}(z)&=\sum _{k=0}^{\infty }{\frac {(z-c)^{k}}{2\pi i}}\int _{\gamma }{\frac {f(w)}{(w-c)^{k+1}}}\,dw\\&={\frac {1}{2\pi i}}\int _{\gamma }{\frac {f(w)}{w-c}}\sum _{k=0}^{\infty }\left({\frac {z-c}{w-c}}\right)^{k}\,dw\\&={\frac {1}{2\pi i}}\int _{\gamma }{\frac {f(w)}{w-c}}\left({\frac {1}{1-{\frac {z-c}{w-c}}}}\right)\,dw\\&={\frac {1}{2\pi i}}\int _{\gamma }{\frac {f(w)}{w-z}}\,dw=f(z),\end{aligned}} ``` You can actually copy equations on Wikipedia, they will be converted into a KaTeX string when you paste it. ```math \displaystyle S[{\boldsymbol {q}}]=\int _{a}^{b}L(t,{\boldsymbol {q}}(t),{\dot {\boldsymbol {q}}}(t))\,dt. ``` # Fumadocs (Framework Mode): Mermaid URL: /docs/markdown/mermaid Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/markdown/mermaid.mdx Rendering diagrams in your docs Fumadocs doesn't have a built-in Mermaid wrapper provided, we recommend using `mermaid` directly. Setup [#setup] Install the required dependencies, `next-themes` is used with Fumadocs to manage the light/dark mode. npm pnpm yarn bun ```bash npm install mermaid next-themes ``` ```bash pnpm add mermaid next-themes ``` ```bash yarn add mermaid next-themes ``` ```bash bun add mermaid next-themes ``` Create the Mermaid component: ```tsx title="components/mdx/mermaid.tsx" 'use client'; import { use, useEffect, useId, useState } from 'react'; import { useTheme } from 'next-themes'; export function Mermaid({ chart }: { chart: string }) { const [mounted, setMounted] = useState(false); useEffect(() => { setMounted(true); }, []); if (!mounted) return; return ; } const cache = new Map>(); function cachePromise(key: string, setPromise: () => Promise): Promise { const cached = cache.get(key); if (cached) return cached as Promise; const promise = setPromise(); cache.set(key, promise); return promise; } function MermaidContent({ chart }: { chart: string }) { const id = useId(); const { resolvedTheme } = useTheme(); const { default: mermaid } = use(cachePromise('mermaid', () => import('mermaid'))); mermaid.initialize({ startOnLoad: false, securityLevel: 'loose', fontFamily: 'inherit', themeCSS: 'margin: 1.5rem auto 0;', theme: resolvedTheme === 'dark' ? 'dark' : 'default', }); const { svg, bindFunctions } = use( cachePromise(`${chart}-${resolvedTheme}`, () => { return mermaid.render(id, chart.replaceAll('\\n', '\n')); }), ); return (

{ if (container) bindFunctions?.(container); }} dangerouslySetInnerHTML={{ __html: svg }} /> ); } ``` > > This is originally inspired by [remark-mermaid](https://github.com/the-guild-org/docs/blob/main/packages/remark-mermaid/src/mermaid.tsx). > Add the component as a MDX component: ```tsx title="mdx-components.tsx" import defaultMdxComponents from 'fumadocs-ui/mdx'; import { Mermaid } from '@/components/mdx/mermaid'; // [!code ++] import type { MDXComponents } from 'mdx/types'; export function getMDXComponents(components?: MDXComponents): MDXComponents { return { ...defaultMdxComponents, Mermaid, // [!code ++] ...components, }; } ``` Usage [#usage] 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="mdx-components.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): MDXComponents { return { ...defaultComponents, // [!code ++] ...Twoslash, ...components, }; } ``` 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 * @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 [``](/docs/ui/root-provider): ```tsx import { RootProvider } from 'fumadocs-ui/provider/'; // [!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): 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. Community Integrations [#community-integrations] A list of integrations maintained by community. * [Trieve Search](/docs/headless/search/trieve) # Fumadocs (Framework Mode): Mixedbread URL: /docs/search/mixedbread Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/search/mixedbread.mdx Using Mixedbread with Fumadocs UI. Setup [#setup] 1. Integrate [Mixedbread Search](/docs/headless/search/mixedbread). 2. Create a search dialog, update `apiKey` and `storeIdentifier` with your desired values. ```tsx title="components/search.tsx" 'use client'; import { SearchDialog, SearchDialogClose, SearchDialogContent, SearchDialogFooter, SearchDialogHeader, SearchDialogIcon, SearchDialogInput, SearchDialogList, SearchDialogOverlay, type SharedProps, } from 'fumadocs-ui/components/dialog/search'; import { useDocsSearch } from 'fumadocs-core/search/client'; import { useI18n } from 'fumadocs-ui/contexts/i18n'; import Mixedbread from '@mixedbread/sdk'; const client = new Mixedbread({ apiKey: 'mxb_xxxx', baseURL: 'https://api.example.com', // Optional, defaults to https://api.mixedbread.com }); export default function CustomSearchDialog(props: SharedProps) { const { locale } = useI18n(); // (optional) for i18n const { search, setSearch, query } = useDocsSearch({ type: 'mixedbread', client, storeIdentifier: 'your_store_identifier', locale, }); return ( Search powered by Mixedbread ); } ``` Replace Search Dialog [#replace-search-dialog] Replace the search dialog with yours from [``](/docs/ui/root-provider): ```tsx import { RootProvider } from 'fumadocs-ui/provider/'; // [!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] 1. Integrate [Orama Cloud](/docs/headless/search/orama-cloud). 2. Create a search dialog, replace `endpoint` and `api_key` with your desired values. ```tsx title="components/search.tsx" 'use client'; import { SearchDialog, SearchDialogClose, SearchDialogContent, SearchDialogFooter, SearchDialogHeader, SearchDialogIcon, SearchDialogInput, SearchDialogList, SearchDialogOverlay, type SharedProps, } from 'fumadocs-ui/components/dialog/search'; import { 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 [``](/docs/ui/root-provider): ```tsx import { RootProvider } from 'fumadocs-ui/provider/'; // [!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 [``](/docs/ui/root-provider): ```tsx import { RootProvider } from 'fumadocs-ui/provider/'; // [!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 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 (

{items.map((item, i) => ( {i !== 0 && } {item.url ? ( {item.name} ) : ( {item.name} )} ))}

); } ``` You can use it by passing the page tree via `tree` prop in a server component. Breadcrumb Item [#breadcrumb-item] # Fumadocs Core (the core library of Fumadocs): Components URL: /docs/headless/components Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/components/index.mdx Blocks for your docs # Fumadocs Core (the core library of Fumadocs): Link URL: /docs/headless/components/link Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/components/link.mdx A Link component that handles external links A component that wraps the Link component of your React framework (e.g. `next/link`) and automatically handles external links in the document.\~ When an external URL is detected, it uses `` instead of the Link Component. The `rel` property is automatically generated. Usage [#usage] Usage is the same as using ``. ```mdx import Link from 'fumadocs-core/link'; Click Me ``` External [#external] You can force a URL to be external by passing an `external` prop. Dynamic hrefs [#dynamic-hrefs] You can enable dynamic hrefs by importing `dynamic-link`. ```mdx import { DynamicLink } from 'fumadocs-core/dynamic-link'; 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. Scroll Provider [#scroll-provider] Scrolls the scroll container to the active anchor. ", "simplifiedType": "object", "required": true, "deprecated": false }, { "name": "children", "description": "", "tags": [], "type": "ReactNode", "simplifiedType": "ReactNode", "required": false, "deprecated": false } ] }} /> TOC Item [#toc-item] An anchor item for jumping to the target anchor. | Data Attribute | Values | Description | | -------------- | ------------- | -------------------- | | `data-active` | `true, false` | Is the anchor active | Example [#example] ```tsx import { AnchorProvider, ScrollProvider, TOCItem, type TOCItemType } from 'fumadocs-core/toc'; import { type ReactNode, useRef } from 'react'; export function Page({ items, children }: { items: TOCItemType[]; children: ReactNode }) { const viewRef = useRef(null); return (

{items.map((item) => ( {item.title} ))}

{children} ); } ``` # Fumadocs Core (the core library of Fumadocs): Content Collections URL: /docs/headless/content-collections Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/content-collections/index.mdx Use Content Collections for Fumadocs [Content Collections](https://www.content-collections.dev) is a library that transforms your content into type-safe data collections. Setup [#setup] Follow their [official guide](https://content-collections.dev/docs) to setup Content Collections for your React framework. Make sure you have MDX configured: npm 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 `` component. ```tsx import { MDXContent } from '@content-collections/mdx/react'; import { getMDXComponents } from '@/mdx-components'; return ; ``` You can also import them in MDX Files, but it is not recommended. 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): 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`. Rehype TOC [#rehype-toc] Exports table of contents (an array of `TOCItemType`), it allows JSX nodes which is not possible with a Remark plugin. > > It requires MDX.js. > Usage [#usage] ```ts import { rehypeToc } from 'fumadocs-core/mdx-plugins'; export default { rehypePlugins: [rehypeToc], }; ``` Output [#output-1] For a Markdown document: ```md ## Hello `code` ``` An export will be created: ```jsx export const toc = [ { title: ( <> Hello 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 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="mdx-components.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): MDXComponents { return { ...defaultComponents, Tab, Tabs, ...components, }; } ``` | 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
          
        
          console...
        
      
    
    ```
  


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]

 void) | undefined",
      "simplifiedType": "function | \"ignore\" | \"hide\" | \"error\"",
      "required": false,
      "deprecated": false
    },
    {
      "name": "useImport",
      "description": "Import images in the file, and let bundlers handle it.\n\n```tsx\nimport MyImage from \"./public/img.png\";\n\n\n```\n\nWhen disabled, `placeholder` will be ignored.",
      "tags": [
        {
          "name": "defaultValue",
          "text": "true"
        }
      ],
      "type": "boolean | undefined",
      "simplifiedType": "boolean",
      "required": false,
      "deprecated": false
    },
    {
      "name": "external",
      "description": "Fetch image size of external URLs",
      "tags": [
        {
          "name": "defaultValue",
          "text": "true"
        }
      ],
      "type": "ExternalImageOptions | undefined",
      "simplifiedType": "object | boolean",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

Example: With Imports [#example-with-imports]

```mdx
![Hello](/hello.png)
![Test](https://example.com/image.png)
```


  Yields:


```mdx
import HelloImage from './public/hello.png';



```


  Where `./public/hello.png` points to the image in public directory.


Example: Without Imports [#example-without-imports]


  For Next.js, you can disable static imports on local images.


```ts
import { remarkImage } from 'fumadocs-core/mdx-plugins';

export default {
  remarkPlugins: [[remarkImage, { useImport: false }]],
};
```

```mdx
![Hello](/hello.png)
![Test](https://example.com/image.png)
```


  Yields:


```mdx


```

Example: Relative Paths [#example-relative-paths]


  When `useImport` is enabled, you can reference local images using relative paths.


```mdx
![Hello](./hello.png)
```


  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 Files
URL: /docs/headless/mdx/remark-mdx-files
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-mdx-files.mdx

Generate files from codeblocks.
        


Introduction [#introduction]


  This plugin takes a codeblock like:


````md
```files
project
├── src
│   ├── index.js
│   └── utils
│       └── helper.js
├── package.json
```
````


  and convert into:


```mdx

  
    
      
      
        
      
    
    
  

```

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 components.



# Fumadocs Core (the core library of Fumadocs): Remark NPM
URL: /docs/headless/mdx/remark-npm
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-npm.mdx

Generate code blocks for package managers
        


Usage [#usage]


  Add the remark plugin.



  
    
      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="mdx-components.tsx"
    import { CodeBlockTabs, CodeBlockTab, CodeBlockTabsList, CodeBlockTabsTrigger } from 'my-ui';
    import type { MDXComponents } from 'mdx/types';

    export function getMDXComponents(components?: MDXComponents): MDXComponents {
      return {
        CodeBlockTabs,
        CodeBlockTab,
        CodeBlockTabsList,
        CodeBlockTabsTrigger,
        ...components,
      };
    }
    ```
  

  
    ```tsx  title="mdx-components.tsx"
    import defaultComponents from 'fumadocs-ui/mdx';
    import type { MDXComponents } from 'mdx/types';

    export function getMDXComponents(components?: MDXComponents): MDXComponents {
      return {
        // it's included by default in `defaultComponents`
        ...defaultComponents,
        ...components,
      };
    }
    ```
  


| 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 ``.



# 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="mdx-components.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): MDXComponents {
  return {
    ...defaultComponents,
    Tab,
    Tabs,
    ...components,
  };
}
```


  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 {children};
}
```
````


  
    
      TypeScript
    

    
      JavaScript
    
  

  
    ```tsx
    import { ReactNode } from 'react';

    export default function Layout({ children }: { children: ReactNode }) {
      return {children};
    }
    ```
  

  
    ```jsx
    export default function Layout({ children }) {
    	return {children};
    }

    ```
  



# 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.


```ts title="MDX Compiler"
import { compile } from '@mdx-js/mdx';
import { remarkStructure } from 'fumadocs-core/mdx-plugins';

const vfile = await compile('...', {
  remarkPlugins: [remarkStructure],
});
```

> 
>   This plugin is included by default on Fumadocs MDX.
> 


  Extracted information could be found in `vfile.data.structuredData`, you may
  write your own plugin to convert it into a MDX export.


Options [#options]

 boolean) | undefined",
      "simplifiedType": "function | array",
      "required": false,
      "deprecated": false
    },
    {
      "name": "allowedMdxAttributes",
      "description": "A list of indexable MDX attributes, either:\n\n- an array of attribute names.\n- a function that determines if attribute should be indexed.",
      "tags": [],
      "type": "string[] | ((node: MdxJsxFlowElement, attribute: MdxJsxAttribute | MdxJsxExpressionAttribute) => boolean) | undefined",
      "simplifiedType": "function | array",
      "required": false,
      "deprecated": false
    },
    {
      "name": "exportAs",
      "description": "export as `structuredData` or specified variable name.",
      "tags": [],
      "type": "string | boolean | undefined",
      "simplifiedType": "boolean | string",
      "required": false,
      "deprecated": false
    }
  ]
}}
/>

Output [#output]


  A list of headings and contents. Paragraphs will be extracted to the `contents`
  array, each item contains a `heading` prop indicating the heading of paragraph.



  A heading can have multiple paragraphs.


Heading [#heading]

| Prop      |                                      |
| --------- | ------------------------------------ |
| `id`      | unique identifier or slug of heading |
| `content` | Text content                         |

Content [#content]

| Prop      |                                 |
| --------- | ------------------------------- |
| `heading` | Heading of paragraph (nullable) |
| `content` | Text content                    |

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';

// the path of pre-rendered `static.json`, choose one according to your React framework
const filePath = {
  next: '.next/server/app/static.json.body',
  'tanstack-start': '.output/public/static.json',
  'react-router': 'build/client/static.json',
  waku: 'dist/public/static.json',
}['next'];

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,
});
```


  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): 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]


  1. Sign up at [Mixedbread](https://platform.mixedbread.com)
  2. Navigate to [API Keys](https://platform.mixedbread.com/platform?next=api-keys)
  3. 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:



  1. Go to the [Stores](https://platform.mixedbread.com/platform?next=stores) in your Mixedbread dashboard
  2. Create a new store for your documentation
  3. 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 Client [#search-client]


  * **Fumadocs UI**: see [Search UI](/docs/search/mixedbread) for details.
  * **Search Client**:

    ```ts
    import { useDocsSearch } from 'fumadocs-core/search/client';

    const mxbai = new Mixedbread({
      apiKey: 'YOUR_API_KEY',
    });

    const client = useDocsSearch({
      type: 'mixedbread',
      client: mxbai,
    });
    ```


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/orama#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: '',
      // ...
    });
    ```



  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.



  1. 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"
     ```

  2. 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',
         });
         ```
       
     

  3. 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';

     // the path of pre-rendered `static.json`, choose one according to your React framework
     const filePath = {
       next: '.next/server/app/static.json.body',
       'tanstack-start': '.output/public/static.json',
       'react-router': 'build/client/static.json',
       waku: 'dist/public/static.json',
     }['next'];

     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();
     ```

  4. 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]


  1. Create a Crawler data source from dashboard, and configure it correctly with the "Documentation" preset.
  2. Copy the credentials from dashboard.


Search Client [#search-client-1]


  Same as REST API integration, but make sure to set `index` to `crawler`.


```ts
import { 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/docs/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/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/docs/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/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',
});
```



Configurations [#configurations]

Tag Filter [#tag-filter]


  Support filtering results by tag, it's useful for implementing multi-docs similar to this documentation.


```ts
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

const server = createFromSource(source, {
  buildIndex(page) {
    return {
      title: page.data.title,
      description: page.data.description,
      url: page.url,
      id: page.url,
      structuredData: page.data.structuredData,
      // use your desired value, like page.slugs[0] [!code ++]
      tag: '',
    };
  },
});
```


  and update your search client:



  * **Fumadocs UI**: Configure [Tag Filter](/docs/search/orama#tag-filter) on Search UI.
  * **Search Client**: pass a tag to 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/docs/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/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',
    });
    ```

     AnyOrama | Promise) | undefined",
          "simplifiedType": "function",
          "required": false,
          "deprecated": false
        },
        {
          "name": "tag",
          "description": "Filter results with specific tag(s).",
          "tags": [],
          "type": "string | string[] | undefined",
          "simplifiedType": "array | string",
          "required": false,
          "deprecated": false
        },
        {
          "name": "locale",
          "description": "Filter by locale (unsupported at the moment)",
          "tags": [],
          "type": "string | undefined",
          "simplifiedType": "string",
          "required": false,
          "deprecated": false
        }
      ]
    }}
    />



  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';

// the path of pre-rendered `static.json`, choose one according to your React framework
const filePath = {
  next: '.next/server/app/static.json.body',
  'tanstack-start': '.output/public/static.json',
  'react-router': 'build/client/static.json',
  waku: 'dist/public/static.json',
}['next'];

const content = fs.readFileSync(filePath);

const records: TrieveDocument[] = JSON.parse(content.toString());

const client = new TrieveSDK({
  apiKey: 'adminApiKey',
  datasetId: 'datasetId',
});

sync(client, records);
```


  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 ;
}
```


  1. Replace `apiKey` and `datasetId` with your desired values.

  2. Replace the default search dialog with your new one.


Search Client [#search-client]


  Add the `useTrieveSearch` hook:


```ts
import { TrieveSDK } from 'trieve-ts-sdk';
import { useTrieveSearch } from 'trieve-fumadocs-adapter/search/trieve';

const client = new TrieveSDK({
  apiKey: 'readOnlyApiKey',
  datasetId: 'datasetId',
});

const { search, setSearch, query } = useTrieveSearch(client);
```

Options [#options]

Tag Filter [#tag-filter]


  To configure tag filtering, add a `tag` value to indexes.


```js
import { sync } from 'trieve-fumadocs-adapter/search/sync';
import { TrieveSDK } from 'trieve-ts-sdk';

const client = new TrieveSDK({
  apiKey: 'adminApiKey',
  datasetId: 'datasetId',
});

const documents = records.map((index) => ({
  ...index,
  tag: 'value', // [!code highlight]
}));

sync(client, documents);
```

Search UI [#search-ui-1]


  Enable Tag Filter.


```tsx title="components/search.tsx"
import SearchDialog from 'trieve-fumadocs-adapter/components/dialog/search';

;
```

Search Client [#search-client-1]


  The `tag_set` field is an attribute for filtering. To filter indexes by tag, use the filter on Trieve search clients.


```json
{
  "must": [
    {
      "field": "tag_set",
      "match": ["value"]
    }
  ]
}
```


  Or with `useTrieveSearch` hook:


```ts
import { TrieveSDK } from 'trieve-ts-sdk';
import { useTrieveSearch } from 'trieve-fumadocs-adapter/search/trieve';

const client = new TrieveSDK({
  apiKey: 'readOnlyApiKey',
  datasetId: 'datasetId',
});

const { search, setSearch, query } = useTrieveSearch(client, undefined, '');
```


# 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 'fumadocs-mdx: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#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 'fumadocs-mdx: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 UI (the default theme of Fumadocs): Accordion
URL: /docs/ui/components/accordion
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/ui/components/accordion.mdx

Add Accordions to your documentation
        




Usage [#usage]


  Based on
  [Radix UI Accordion](https://www.radix-ui.com/primitives/docs/components/accordion), useful for FAQ sections.


> 
>   For `@fumadocs/base-ui`, this is based on [Base UI](https://base-ui.com/react/components/accordion) instead.
> 


  Use it in MDX files or as a normal React component.



  
    
      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]



Accordion [#accordion]



Linking to Accordion [#linking-to-accordion]


  You can specify an `id` for accordion. The accordion will automatically open when the user is navigating to the page with the specified `id` in hash parameter.


```mdx



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
        



     string",
        "simplifiedType": "function",
        "required": true,
        "deprecated": false
      },
      {
        "name": "options",
        "description": "We love Shiki.\n\n```ts\nconsole.log(\"Hello World, powered by Shiki\");\n```",
        "tags": [
          {
            "name": "default",
            "text": "{ a: \"test\" }"
          }
        ],
        "type": "Partial<{ a: unknown; }> | undefined",
        "simplifiedType": "Partial

Good Heading

{props.title}

Page Not Found

This heading looks good!

This heading looks good!

{frontmatter.title}

{frontmatter.title}

{page.data.title}