Fumadocs MDX

Fumadocs MDX Usage Guide

Manage Fumadocs content collections and MDX documents.

Define Content Collections

Doc Type

Markdown/MDX document files:

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    title: z.string(),
    date: z.string().optional(),
    tags: z.array(z.string()).default([]),
    featured: z.boolean().default(false),
  }),
  mdxOptions: {
    remarkPlugins: [remarkAdmonition()],
    rehypePlugins: [rehypeCode()],
  },
});

Meta Type

JSON/YAML metadata files:

export const metaFiles = defineCollections({
  type: 'meta',
  dir: './content/meta',
  schema: z.object({
    name: z.string(),
    url: z.string(),
    description: z.string().optional(),
  }),
  files: ['config.json', 'meta/*.json'],
});

Schema Definition

Using Zod

schema: z.object({
  title: z.string().min(10),
  description: z.string().max(200),
  published: z.coerce.date(),
  author: z.string(),
});

Using Function

schema: (ctx) => {
  return z.object({
    title: z.string(),
    path: z.string().default(ctx.path),
    filename: z.string().default(ctx.filename),
  });
}

Standard Schema

Supports standard Schema-compatible libraries, such as Zod.

MDX Options

Preset Configuration

import { applyMdxPreset } from 'fumadocs-mdx/mdx';

export const docs = defineCollections({
  type: 'doc',
  mdxOptions: applyMdxPreset({
    remarkPlugins: [remarkAdmonition()],
    rehypePlugins: [rehypeCode()],
  }),
});

Disable Preset

mdxOptions: {
  // Completely custom
  remarkPlugins: [remarkAdmonition()],
  rehypePlugins: [rehypeCode()],
}

Postprocess API

Include Processed Markdown

export const docs = defineDocs({
  docs: {
    postprocess: {
      includeProcessedMarkdown: true,
    },
  },
});

Access:

const page = await page.data.getText('processed');

// Use processed markdown
const html = await page.data.getHtml();

Export Build-Time Data

export const docs = defineDocs({
  docs: {
    postprocess: {
      valueToExport: ['metadata', 'toc'],
    },
  },
});

Access in MDX files:

// content/docs/guide.mdx
export const metadata = {
  title: 'My Guide',
  date: '2024-01-01',
};

export const toc = {
  heading: 'Getting Started',
};

Import in other files:

import { metadata, toc } from './guide.mdx';

Workspace Support

Multi-Workspace

export default defineDocs({
  dir: 'content/docs',
  docs: {
    dir: 'guides',
  },
  meta: {
    dir: 'metadata',
  },
  blog: {
    dir: 'content/blog',
  },
});

Custom Collectors

export default defineDocs({
  dir: 'content/docs',
  collections: {
    posts: defineCollections({
      type: 'doc',
      dir: 'content/blog',
    }),
    meta: defineCollections({
      type: 'meta',
      dir: 'metadata',
    }),
  },
});

TypeScript Type Generation

Generate Types

npx fumadocs-mdx typegen

Skip Dev Server

npx fumadocs-mdx typegen --skip-dev-server

Output to Specific File

npx fumadocs-mdx typegen --out-file src/types.d.ts

Add Script in package.json

{
  "scripts": {
    "typegen": "fumadocs-mdx typegen"
  }
}

File Imports

Import from Other Files

import { include } from 'fumadocs-mdx/include';

export const sharedContent = include({
  path: './content/shared/intro.mdx',
});

export const footerContent = include({
  path: './content/shared/footer.mdx',
});

Dynamic Import

export const docs = defineCollections({
  type: 'doc',
  dir: './content/docs',
  dynamic: true,
});

Batch Import

import { include } from 'fumadocs-mdx/include';

export const components = include({
  path: './content/components/*.mdx',
});

Performance Optimization

Lazy Loading

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  async: true,
  schema: z.object({
    title: z.string(),
  }),
});

Disable Lazy Loading

export const docs = defineCollections({
  type: 'doc',
  dir: './content/docs',
  async: false,
});

Content Authoring

Frontmatter

---
title: "My Document"
description: "A brief description"
date: "2024-01-01"
tags: ["guide", "tutorial"]
draft: false
---

# My Document

Content here...

Custom Properties

---
title: "API Reference"
apiVersion: "1.0.0"
endpoint: "/api/v1/users"
---

# API Reference

Markdown Features

Math Formulas

import { remarkMath } from 'fumadocs-mdx/mdx';
import { rehypeKatex } from 'rehype-katex';

export const docs = defineDocs({
  type: 'doc',
  mdxOptions: {
    remarkPlugins: [remarkMath()],
    rehypePlugins: [rehypeKatex()],
  },
});

Mermaid Diagrams

import { remarkMermaid } from 'fumadocs-mdx/mdx';

export const docs = defineDocs({
  type: 'doc',
  mdxOptions: {
    remarkPlugins: [remarkMermaid()],
  },
});

```mermaid
graph LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

### Twoslash

```typescript
import { remarkTwoslash } from 'fumadocs-mdx/mdx';

export const docs = defineDocs({
  type: 'doc',
  mdxOptions: {
    remarkPlugins: [remarkTwoslash()],
  },
});

function greet(name: string): string {
  return `Hello, ${name}!`;
}

Reference Documentation:

• MDX Documentation
• Collections Configuration
• Global Options
• MDX Preset
• TypeScript Type Generation