Content Collections Adapter

Overview

The Content Collections Adapter (@fumadocs/content-collections) bridges Content Collections data layers with Fumadocs by supplying factory functions and transformation pipelines that translate content entries into compatible virtual files and sources.

Sources: packages/content-collections/package.json:2-4, packages/content-collections/src/index.ts:4-10

By normalizing schemas, unifying metadata extensions, and configuring remark/rehype pipelines such as heading generation and code block formatting, the package enables type-safe content management and rendering across Fumadocs applications.

Sources: packages/content-collections/src/types.ts:4-9, packages/content-collections/src/configuration.ts:58-71

Package architecture and integration entry

Public Exports and Bundle Configuration

The @fumadocs/content-collections package (@fumadocs/content-collections) is structured as an ESM-only module targeting Node 22, configured via tsdown with TypeScript declaration generation enabled (dts: true) and fixed file extensions disabled. The package exposes two public entry points mapped in package exports: the root entry . resolving to ./dist/index.js (with type definitions at ./dist/index.d.ts) and ./configuration resolving to ./dist/configuration.js (with type definitions at ./dist/configuration.d.ts).

Copyimport { defineConfig } from 'tsdown';
 
export default defineConfig({
  dts: true,
  fixedExtension: false,
  target: 'node22',
  format: 'esm',
  entry: ['src/{index,configuration}.ts'],
  deps: {
    onlyBundle: [],
  },
});

Sources: packages/content-collections/tsdown.config.ts:1-12

Copy"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "import": "./dist/index.js"
  },
  "./configuration": {
    "types": "./dist/configuration.d.ts",
    "import": "./dist/configuration.js"
  }
},

Sources: packages/content-collections/package.json:17-29

Package Dependencies and Peer Requirements

Package execution relies on runtime dependencies for unified document processing and schema validation, alongside peer dependencies that couple the adapter directly with Content Collections core packages and Fumadocs core.

Sources: packages/content-collections/package.json:40-56

Data contract and schema inheritance

Interface Definitions

The data contract between Content Collections and Fumadocs relies on two core TypeScript interfaces: BaseMetaData and BaseDocsData. These interfaces extend Fumadocs core metadata and page data types by injecting the _meta property defined by @content-collections/core.

Copyexport interface BaseMetaData extends MetaData {
  _meta: Meta;
}
 
export interface BaseDocsData extends PageData {
  _meta: Meta;
}

Sources: packages/content-collections/src/types.ts:4-10

Sources: packages/content-collections/src/index.ts:23-31, packages/content-collections/src/types.ts:4-10

Type Parameter Constraints

The createMDXSource factory function enforces schema inheritance through generic type constraints bounded by BaseDocsData and BaseMetaData. Documents (allDocs) and metadata files (allMetas) must conform to these extended data models to produce a typed Source containing metaData and pageData.

Copyexport function createMDXSource<Docs extends BaseDocsData, Meta extends BaseMetaData>(
  allDocs: Docs[],
  allMetas: Meta[],
): Source<{
  metaData: Meta;
  pageData: Docs;
}> {

Sources: packages/content-collections/src/index.ts:4-10

Plugin configuration and remark pipelines

Transform Options and Default Processors

The transformMDX function processes documents by invoking baseCompileMDX from @content-collections/mdx while applying a customized pipeline of remark and rehype plugins [packages/content-collections/src/configuration.ts:58-97]. The transformation accepts TransformOptions, which inherit from core MDX options while omitting raw plugin arrays in favor of customizable ResolvePlugins inputs for both remarkPlugins and rehypePlugins packages/content-collections/src/configuration.ts:13-15.

Copyexport interface TransformOptions extends Omit<MDXOptions, 'remarkPlugins' | 'rehypePlugins'> {
  remarkPlugins?: ResolvePlugins;
  rehypePlugins?: ResolvePlugins;
 
  /**
   * Generate `structuredData`
   *
   * @defaultValue true
   * @deprecated use `remarkStructureOptions` instead
   */
  generateStructuredData?: boolean;
 
  remarkStructureOptions?: Plugins.StructureOptions | boolean;
  remarkHeadingOptions?: Plugins.RemarkHeadingOptions | boolean;
  rehypeCodeOptions?: Plugins.RehypeCodeOptions | boolean;
  remarkImageOptions?: Plugins.RemarkImageOptions | boolean;
  remarkCodeTabOptions?: Plugins.RemarkCodeTabOptions | boolean;
}

Sources: packages/content-collections/src/configuration.ts:13-30

Sources: packages/content-collections/src/configuration.ts:72-80, packages/content-collections/src/configuration.ts:108-110

Resolution Pipeline and File Data Extraction

Plugins are resolved using resolvePlugins and resolvePlugin, merging user-provided options with Fumadocs defaults packages/content-collections/src/configuration.ts:100-122. A final custom visitor function is appended to the remark pipeline to capture runtime file.data properties generated by plugins like table of contents extraction and structured data processing packages/content-collections/src/configuration.ts:114-120.

Copy    rehypePlugins: resolvePlugins(
      (plugins) => [resolvePlugin(Plugins.rehypeCode, rehypeCodeOptions), ...plugins],
      rest.rehypePlugins,
    ),
    remarkPlugins: resolvePlugins(
      (plugins) => [
        Plugins.remarkGfm,
        resolvePlugin(Plugins.remarkHeading, remarkHeadingOptions),
        resolvePlugin(Plugins.remarkImage, remarkImageOptions, {
          useImport: false,
        }),
        'remarkCodeTab' in Plugins &&
          resolvePlugin(Plugins.remarkCodeTab, remarkCodeTabOptions),
        ...plugins,
        resolvePlugin(Plugins.remarkStructure, remarkStructureOptions),
        () => {
          return (_, file) => {
            data = file.data;
          };
        },
      ],
      rest.remarkPlugins,
    ),
  },
);

Sources: packages/content-collections/src/configuration.ts:100-124

Sources: packages/content-collections/src/configuration.ts:90-95

Virtual file mapping and sources

Creating MDX Sources

The createMDXSource function bridges raw Content Collections arrays into a structured Fumadocs source object packages/content-collections/src/index.ts:4-10. It accepts allDocs and allMetas collections conforming to BaseDocsData and BaseMetaData respectively, returning a unified Source object containing typed metaData and pageData generics packages/content-collections/src/index.ts:4-10.

Copyexport function createMDXSource<Docs extends BaseDocsData, Meta extends BaseMetaData>(
  allDocs: Docs[],
  allMetas: Meta[],
): Source<{
  metaData: Meta;
  pageData: Docs;
}> {

Sources: packages/content-collections/src/index.ts:4-10]

Copytype File = VirtualFile<{
  metaData: Meta;
  pageData: Docs;
}>;
 

Sources: packages/content-collections/src/index.ts:11-15]

File Mapping Structure

The returned source maps each document and metadata record into a typed VirtualFile array packages/content-collections/src/index.ts:16-35. Document entries are mapped with a 'page' type, retaining their original data and path derived from v._meta.filePath packages/content-collections/src/index.ts:18-25. Metadata entries are mapped with a 'meta' type using the same path extraction strategy packages/content-collections/src/index.ts:26-33.

Copyreturn {
  files: [
    ...allDocs.map(
      (v) =>
        ({
          type: 'page',
          data: v,
          path: v._meta.filePath,
        }) satisfies File,
    ),
    ...allMetas.map(
      (v) =>
        ({
          type: 'meta',
          data: v,
          path: v._meta.filePath,
        }) satisfies File,
    ),
  ],
};

Sources: packages/content-collections/src/index.ts:16-35]

Sources: packages/content-collections/src/index.ts:18-33, packages/content-collections/src/types.ts:4-10

Sources: packages/content-collections/src/index.ts:24, packages/content-collections/src/index.ts:32

Collection definition and schema spec

Collection Definition Primitives

Fumadocs provides content definition helpers such as defineDocs, defineCollections, and docsCollection to structure documentation workspaces. The defineDocs helper accepts a target directory and configuration overrides for documentation and metadata collections, defaulting to content/docs when no directory is specified packages/mdx/src/config/define.ts:112-144.

Copyexport function defineDocs<
  DocSchema extends StandardSchemaV1 = typeof pageSchema,
  MetaSchema extends StandardSchemaV1 = typeof metaSchema,
>(options: {
  dir?: string;
  docs?: Omit<DocCollection<DocSchema>, 'dir' | 'type'>;
  meta?: Omit<MetaCollection<MetaSchema>, 'dir' | 'type'>;
}): DocsCollection<DocSchema, MetaSchema> {
  const dir = options.dir ?? 'content/docs';
 
  return {
    type: 'docs',
    dir,
    docs: defineCollections({
      type: 'doc',
      dir,
      schema: pageSchema as any,
      ...options?.docs,
    }),
    meta: defineCollections({
      type: 'meta',
      dir,
      schema: metaSchema as any,
      ...options?.meta,
    }),
  };
}

Sources: packages/mdx/src/config/define.ts:112-144]

Standard Schema Validation Specifications

Collections enforce runtime data integrity using the Standard Schema specification (StandardSchemaV1), supporting static schemas or context-aware schema generator functions packages/content/src/index.ts:1-14, packages/mdx/src/config/define.ts:9-12. The docsCollection factory constructs combined MDX document collections and JSON/YAML metadata collections backed by pageSchema and metaSchema defaults packages/content/src/index.ts:35-53.

Sources: packages/content/src/index.ts:35-53, packages/mdx/src/config/define.ts:9-12, packages/mdx/src/config/define.ts:112-144]

Sources: packages/mdx/src/config/define.ts:9-12]

Related

• Source Loader