Collections

Define Collections

Define a collection to parse a certain set of files.

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    // allowed...
  }),
});

Prop	Type	Default
`dir`	`string \| string[]`	-
`files`	`string[]`	-
`schema`	`Schema \| ((ctx: TransformContext) => Schema)`	-
`type`	`Type`	-
`transform`	`(entry: CollectionEntry<Type, output<Schema>>, globalConfig?: GlobalConfig \| undefined) => Output \| Promise<Output>`	-
`mdxOptions`	`Type extends "doc" ? MDXOptions : never`	-

`dir`

Directories to scan input files.

`schema`

The Zod schema to validate file data (frontmatter on doc type, content on meta type).

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    name: z.string(),
  }),
});

You can add additional properties to the output. Note that the validation is done by build time, hence the output must be serializable.

You can also pass a function and receives the transform context.

import { defineCollections } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: (ctx) => {
    return z.object({
      name: z.string(),
      testPath: z.string().default(ctx.path),
    });
  },
});

`type`

The accepted type of collection.

Type	Description
`meta`	JSON/YAML File
`doc`	Markdown/MDX Documents

import { defineCollections } from 'fumadocs-mdx/config';
 
// only scan for json/yaml files
export const metaFiles = defineCollections({
  type: 'meta',
});

`mdxOptions`

Customise MDX options on collection level.

source.config.ts

import { defineCollections, getDefaultMDXOptions } from 'fumadocs-mdx/config';
 
export const blog = defineCollections({
  type: 'doc',
  mdxOptions: {
    // mdx options
  },
});

By design, this will remove all default settings applied by your global config and Fumadocs MDX.

With Defaults

Use getDefaultMDXOptions to apply default configurations, it accepts the Extended MDX Options.

source.config.ts

import { defineCollections, getDefaultMDXOptions } from 'fumadocs-mdx/config';
 
export const blog = defineCollections({
  type: 'doc',
  mdxOptions: getDefaultMDXOptions({
    // extended mdx options
  }),
});

For full control over MDX options, you can pass MDX options without it, which means no defaults will be applied.

This API only available on doc type.

`transform`

A function to perform runtime transformation on collection entries.

See Transform.

Define Docs

You can use defineDocs to define the required collections to work with Fumadocs. It offers the same API as defineCollections.

import { defineDocs } from 'fumadocs-mdx/config';
 
export const { docs, meta } = defineDocs({
  docs: {
    // optional, you can pass options to each collection
  },
  meta: {
    // optional, you can pass options to each collection
  },
});

The docs and meta are collections on their own. You can pass collection options to them as shown above.

`dir`

Instead of per collection, you should customise dir from defineDocs:

import { defineDocs } from 'fumadocs-mdx/config';
 
export const { docs, meta } = defineDocs({
  dir: 'my/content/dir',
});

`schema`

You can extend the default Zod schema of docs and meta.

import { frontmatterSchema, metaSchema, defineDocs } from 'fumadocs-mdx/config';
import { z } from 'zod';
 
export const { docs, meta } = defineDocs({
  docs: {
    schema: frontmatterSchema.extend({
      index: z.boolean().default(false),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      // other props
    }),
  },
});

On this page