Skip to Content
Fumadocs

Source

Setup sources for Loader API

Overview

Content loader accepts different content sources based on a source interface.

Multiple Sources

Pass a record of source objects instead

import { loader } from 'fumadocs-core/source';
import { blog, docs } from 'collections/server';
import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons';

export const source = loader(
  {
    docs: docs.toFumadocsSource(),
    openapi: blog.toFumadocsSource(),
  },
  {
    baseUrl: '/docs',
  },
);

To access properties exclusive to each source:

const page = source.getPage(['...']);

if (page.type === 'docs') {
  console.log(page.data);
} else {
  console.log(page.data);
}

Static Source

To plug your own content source, create a StaticSource object.

Since Loader API doesn't rely on file system, file paths only allow virtual paths like file.mdx and content/file.mdx, ./file.mdx and D://content/file.mdx are not allowed.

import type {  } from 'fumadocs-core/source';

export function (): <{
  : { : string; : string[] }; // Your custom type
  : { : string; ?: string }; // Your custom type
}> {
  return {
    : [
      {
        : 'page',
        : 'folder/index.mdx',
        : {
          : 'Hello World',
          // ...
        },
      },
      {
        : 'meta',
        : 'meta.json',
        : {
          : 'Docs',
          : ['folder'],
          // ...
        },
      },
    ],
  };
}

With i18n, the language of a file is parsed from its path, unless the file specifies a locale.

Dynamic Source

For content sources with revalidation, return a DynamicSource instead:

import type { DynamicSource } from 'fumadocs-core/source';

export function createMySource(): DynamicSource<{
  metaData: { title: string; pages: string[] };
  pageData: { title: string; description?: string };
}> {
  return {
    async files() {
      return [
        {
          type: 'page',
          path: 'folder/index.mdx',
          data: {
            title: 'Hello World',
          },
        },
        {
          type: 'meta',
          path: 'meta.json',
          data: {
            title: 'Docs',
            pages: ['folder'],
          },
        },
      ];
    },
    configure(loader) {
      // you can revalidate the loader from source, e.g.
      onMyEvent(() => {
        void loader.revalidate();
      });
    },
  };
}

Dynamic sources can only be consumed by dynamicLoader().

Path Params

To support path params in your source, pass a file like [framework]/deploy.mdx as one virtual file. The loader generates a page for each value, with the data from dataAt(), or data without it. Meta files work the same way:

import type {  } from 'fumadocs-core/source';

const : ['files'] = [
  {
    : 'page',
    : '[framework]/deploy.mdx',
    : { : 'Deploy' },
    : () => ({ : `Deploy on ${.framework}` }),
  },
  {
    : 'meta',
    : '[framework]/meta.json',
    : { : [{ : 'waku' }, { : 'astro' }] },
    : () => ({ : .framework }),
  },
];

Listing Params

To resolve the data of each value ahead of the loader, like frontmatter in code, getStaticParams() lists the params with the same rules. It reads the staticParams of meta files from your storage, by their paths without extension:

const  = ('[framework]/deploy.mdx', {
  : .,
  : () => .()?.,
});

It returns undefined when nothing lists the values. The file is then one page at its literal path.

Custom Props

To support custom props, dataAt() takes them as a second argument, with the page data after the loader plugins. Return that data rendered for the params and custom props:

const : ['files'] = [
  {
    : 'page',
    : '[framework]/deploy.mdx',
    : ({}),
    : (, ) =>
       ? { ...., ...({ ..., .... }) } : (),
  },
];

A page without dataAt() ignores custom props.

Runtime Outputs

If your source compiles MDX, compile each file once and pass the page props to its content. To generate the table of contents, search records and Markdown with the same props:

  • set unstable_runtimeOutputs: true in the data of the file you compile. On Sätteri, set it in the data of the compile options.
  • add rehypeHeading as your last rehype plugin, to generate heading IDs from the rendered text.
import { VFile } from 'vfile';

const file = new VFile({
  path: '[framework]/deploy.mdx',
  value: source,
  data: { unstable_runtimeOutputs: true },
});

The plugins then export functions instead of values, like toc of Rehype TOC and the _markdown component of Remark LLMs. Call them with the props of each page:

const { : , , :  } = ;

function (: object) {
  return {
    : 'Deploy',
    : (: MDXProps) => < {...} {...} />,
    : (),
    : () => (< {...} />),
    : ..,
  };
}

const : ['files'] = [
  {
    : 'page',
    : '[framework]/deploy.mdx',
    : ({}),
    : () => (),
  },
];

For search, read the records of Remark Structure from file.data.structuredData, not from the export. They include every <show> branch, and expressions keep their source text.

The unstable_ prefix means the API may change. Without the flag, a document with <show> fails to compile when Rehype TOC, Remark Structure or Remark LLMs runs.

How is this guide?