Skip to Content
Fumadocs

Collections

Collection of content data for your app

Define Collections

Define a collection to parse a certain set of files. The examples on this page define collections in source.config.ts, while the Macro API defines them in lib/source.ts with largely the same options.

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

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  schema: z.object({
    // schema
  }),
  // other options
});

type

The accepted type of collection.

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

// only scan for meta files
export const metaFiles = defineCollections({
  type: 'meta',
  // options
});
  • type: meta

    Accept JSON/YAML files and code modules (meta.ts or meta.js) with a default export. See Meta. Available options:

    Prop

    Type

  • type: doc

    Markdown/MDX documents, available options:

    Prop

    Type

schema

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

Standard Schema compatible libraries, including Zod, are supported.

Note that the validation is done at build time, hence the output must be serializable. You can also pass a function that 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(
        // absolute path of the file
        ctx.path,
      ),
    });
  },
});

mdxOptions

Customize MDX options at the collection level, for collections compiled with unified.

This API is only available on doc type.

source.config.ts
import { defineCollections } from 'fumadocs-mdx/config';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  mdxOptions: {
    // mdx options
  },
});

By design, this will remove all default settings applied by your global config and Fumadocs MDX. You have full control over MDX options.

You can use applyMdxPreset to apply the default MDX preset.

source.config.ts
import { applyMdxPreset, defineCollections } from 'fumadocs-mdx/config';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  mdxOptions: applyMdxPreset({
    // extend the preset
  }),
});

compiler

This API is only available on doc type.

Compile the collection with Sätteri instead of unified, and pass satteriOptions in place of mdxOptions.

source.config.ts
import { defineCollections } from 'fumadocs-mdx/config';

export const blog = defineCollections({
  type: 'doc',
  dir: './content/blog',
  compiler: 'satteri',
  // optional, defaults to the global `satteriOptions`
  satteriOptions: {
    // Sätteri options
  },
});

Unlike mdxOptions, the collection-level satteriOptions keeps the default preset unless you pass preset: 'minimal'. It replaces the global satteriOptions instead of merging with them.

postprocess

This API is only available on doc type.

You can pass build-time information to runtime using the postprocess API.

  • includeProcessedMarkdown

    Export the Markdown of documents, generated by Remark LLMs. Pass true or its options.

    import { defineDocs } from 'fumadocs-mdx/config';
    
    export default defineDocs({
      docs: {
        postprocess: {
          includeProcessedMarkdown: true,
        },
      },
    });

    Read it with getText('processed'), e.g. from loader():

    import { source } from '@/lib/source';
    
    const page = source.getPage('...');
    console.log(await page.data.getText('processed'));
  • valueToExport

    Some remark plugins store their output in vfile.data (compile-time memory) which cannot be accessed from your code.

    You can specify the name of properties to include, they will get converted into ESM exports that you can access when importing the MDX file.

    import { defineDocs } from 'fumadocs-mdx/config';
    
    export default defineDocs({
      docs: {
        postprocess: {
          valueToExport: ['dataName'],
        },
      },
    });

Define Docs

Define a collection for Fumadocs.

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: '/my/content/dir',
  docs: {
    // optional, options of `doc` collection
  },
  meta: {
    // optional, options of `meta` collection
  },
});

dir

Instead of per collection, you should customize content directory from defineDocs:

import { defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  dir: 'content/guides',
});

schema

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

import { defineDocs } from 'fumadocs-mdx/config';
import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
import { z } from 'zod';

export const docs = defineDocs({
  docs: {
    schema: pageSchema.extend({
      index: z.boolean().default(false),
    }),
  },
  meta: {
    schema: metaSchema.extend({
      // other props
    }),
  },
});

How is this guide?