The configuration API allows you to define content collections and customize MDX processing behavior.
defineConfig
Defines global configuration for Fumadocs MDX.
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
plugins: [],
mdxOptions: {
remarkPlugins: [],
rehypePlugins: []
},
workspaces: {},
experimentalBuildCache: '.cache'
});
Array of plugins to extend functionality
mdxOptions
MDXPresetOptions | (() => Promise<MDXPresetOptions>)
Global MDX processor options or async function returning options
workspaces
Record<string, { dir: string; config: Record<string, unknown> }>
Multi-workspace configuration for monorepos
Directory path for build cache storage (disabled in development)
defineCollections
Defines a single content collection.
Document Collection
import { defineCollections, frontmatterSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';
export const docs = defineCollections({
type: 'doc',
dir: 'content/docs',
files: ['**/*.mdx'],
schema: frontmatterSchema.extend({
author: z.string().optional()
}),
mdxOptions: {
remarkPlugins: []
},
postprocess: {
extractLinkReferences: true
},
async: false,
dynamic: false
});
Collection type for documents
Directory to scan for files
Glob patterns for files to include (default: **/*.{md,mdx})
schema
StandardSchemaV1 | ((ctx) => StandardSchemaV1)
Zod schema for validating frontmatter, or function returning schema
mdxOptions
ProcessorOptions | ((environment) => Promise<ProcessorOptions>)
Collection-specific MDX options
postprocess
Partial<PostprocessOptions>
Post-processing configuration for extracting data
Load files asynchronously for code splitting
Compile files on-demand at runtime
import { defineCollections, metaSchema } from 'fumadocs-mdx/config';
export const meta = defineCollections({
type: 'meta',
dir: 'content/docs',
files: ['**/meta.json'],
schema: metaSchema
});
Collection type for metadata files
Directory to scan for metadata files
Glob patterns (default: **/*.{json,yaml})
schema
StandardSchemaV1 | ((ctx) => StandardSchemaV1)
Zod schema for validation
defineDocs
Defines a combined docs collection with both documents and metadata.
import { defineDocs, frontmatterSchema, metaSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';
export const docs = defineDocs({
dir: 'content/docs',
docs: {
schema: frontmatterSchema,
mdxOptions: {},
postprocess: {}
},
meta: {
schema: metaSchema
}
});
dir
string
default:"'content/docs'"
Base directory for both docs and meta files
docs
Omit<DocCollection, 'dir' | 'type'>
Document collection configuration
meta
Omit<MetaCollection, 'dir' | 'type'>
Metadata collection configuration
MDX Options
MDXPresetOptions
Configure MDX processing with Fumadocs presets.
interface MDXPresetOptions {
preset?: 'fumadocs' | 'minimal';
remarkPlugins?: Pluggable[] | ((v: Pluggable[]) => Pluggable[]);
rehypePlugins?: Pluggable[] | ((v: Pluggable[]) => Pluggable[]);
valueToExport?: string[];
remarkStructureOptions?: StructureOptions | false;
remarkHeadingOptions?: RemarkHeadingOptions;
remarkImageOptions?: RemarkImageOptions | false;
remarkCodeTabOptions?: RemarkCodeTabOptions | false;
remarkNpmOptions?: RemarkNpmOptions | false;
rehypeCodeOptions?: RehypeCodeOptions | false;
}
preset
'fumadocs' | 'minimal'
default:"'fumadocs'"
fumadocs: Full plugin suite with GFM, headings, images, code highlightingminimal: No default plugins, bring your own
Remark plugins array or transform function
rehypePlugins
Pluggable[] | ((plugins: Pluggable[]) => Pluggable[])
Rehype plugins array or transform function
Additional properties from vfile.data to export
Configure structure extraction or disable with false
Heading processing configuration
Image optimization settings or false to disable
npm package reference options
rehypeCodeOptions
RehypeCodeOptions | false
Code highlighting configuration or false to disable
Example: Custom Plugins
import { defineConfig } from 'fumadocs-mdx/config';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';
export default defineConfig({
mdxOptions: {
remarkPlugins: (plugins) => [...plugins, remarkMath],
rehypePlugins: (plugins) => [...plugins, rehypeKatex]
}
});
PostprocessOptions
Configure post-processing of MDX content.
interface PostprocessOptions {
valueToExport?: string[];
includeProcessedMarkdown?: boolean | {
headingIds?: boolean;
};
extractLinkReferences?: boolean;
includeMDAST?: boolean | {
removePosition?: boolean;
};
}
Export additional properties from vfile.data
includeProcessedMarkdown
boolean | { headingIds?: boolean }
Export processed markdown as _markdown. Include heading IDs with { headingIds: true }
Extract link references and export as extractedReferences
includeMDAST
boolean | { removePosition?: boolean }
Export MDAST tree as _mdast. Strip position info with { removePosition: true }
export const docs = defineCollections({
type: 'doc',
dir: 'content/docs',
postprocess: {
extractLinkReferences: true
}
});
import { extractedReferences } from './page.mdx';
// extractedReferences: Array<{ href: string }>
Built-in Schemas
frontmatterSchema
Default schema for page frontmatter.
import { frontmatterSchema } from 'fumadocs-mdx/config';
import { z } from 'zod';
const customSchema = frontmatterSchema.extend({
author: z.string(),
tags: z.array(z.string()).default([])
});
import { metaSchema } from 'fumadocs-mdx/config';
Collection Types
DocCollection
interface DocCollection<Schema extends StandardSchemaV1 = StandardSchemaV1> {
type: 'doc';
dir: string;
files?: string[];
postprocess?: Partial<PostprocessOptions>;
mdxOptions?: ProcessorOptions | ((environment: BuildEnvironment) => Promise<ProcessorOptions>);
async?: boolean;
dynamic?: boolean;
schema?: CollectionSchema<Schema, { path: string; source: string }>;
}
interface MetaCollection<Schema extends StandardSchemaV1 = StandardSchemaV1> {
type: 'meta';
dir: string;
files?: string[];
schema?: CollectionSchema<Schema, { path: string; source: string }>;
}
DocsCollection
interface DocsCollection<
DocSchema extends StandardSchemaV1 = StandardSchemaV1,
MetaSchema extends StandardSchemaV1 = StandardSchemaV1
> {
type: 'docs';
dir: string;
docs: DocCollection<DocSchema>;
meta: MetaCollection<MetaSchema>;
}
Workspaces
Configure multiple content sources in a monorepo:
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
export default defineConfig({
workspaces: {
blog: {
dir: 'packages/blog',
config: {
posts: defineDocs({ dir: 'content' })
}
},
docs: {
dir: 'packages/docs',
config: {
guides: defineDocs({ dir: 'content/guides' })
}
}
}
});
import page from './content/page.mdx?collection=posts&workspace=blog';
Environment Configuration
MDX options can adapt to the build environment:
export const docs = defineCollections({
type: 'doc',
dir: 'content/docs',
mdxOptions: async (environment) => {
// environment: 'bundler' | 'runtime'
return {
remarkPlugins: environment === 'bundler'
? [/* bundler-specific plugins */]
: [/* runtime plugins */]
};
}
});