loader()

Usage

loader() provides an interface for Fumadocs to integrate with file-system based content sources.

What it does?

Generate page slugs and page tree.
Assign URL to each page.
Output useful utilities to interact with content.

It doesn't rely on the real file system (zero node:fs usage), a virtual storage is also allowed.

You can use it with built-in content sources like Fumadocs MDX.

import { loader } from 'fumadocs-core/source';
import { docs } from '@/.source';

export const source = loader({
  source: docs.toFumadocsSource(),
});

URL

You can override the base URL, or specify a function to generate URL for each page.

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

loader({
  baseUrl: '/docs',
  // or you can customise it with function
  url(slugs, locale) {
    if (locale) return '/' + [locale, 'docs', ...slugs].join('/');
    return '/' + ['docs', ...slugs].join('/');
  },
});

Icons

Load the icon property specified by pages and meta files.

import { loader } from 'fumadocs-core/source';
import { icons } from 'lucide-react';
import { createElement } from 'react';

loader({
  icon(icon) {
    if (!icon) {
      // You may set a default icon
      return;
    }

    if (icon in icons) return createElement(icons[icon as keyof typeof icons]);
  },
});

I18n

Pass the i18n config to loader.

lib/source.ts

import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n,
});

With i18n enabled, loader will generate a page tree for every locale.

If translations are missing for a page, it fallbacks to fallbackLanguage.

Output

The loader outputs a source object.

Get Page

Get page with slugs.

import { source } from '@/lib/source';

source.getPage(['slug', 'of', 'page']);

// with i18n
source.getPage(['slug', 'of', 'page'], 'locale');

Get Pages

Get a list of page available for locale.

import { source } from '@/lib/source';

// from any locale
source.getPages();

// for a specific locale
source.getPages('locale');

Page Tree

import { source } from '@/lib/source';

// without i18n
source.pageTree;

// with i18n
source.pageTree['locale'];

Get from Node

The page tree nodes contain references to their original file path. You can find their original page or meta file from the tree nodes.

import { source } from '@/lib/source';

source.getNodePage(pageNode);
source.getNodeMeta(folderNode);

Params

A function to generate output for Next.js generateStaticParams. The generated parameter names will be slug: string[] and lang: string (i18n only).

app/[[...slug]]/page.tsx

import { source } from '@/lib/source';

export function generateStaticParams() {
  return source.generateParams();
}

Language Entries

Get available languages and its pages.

import { source } from '@/lib/source';

// language -> pages
const entries = source.getLanguages();

Plugins

You can create loader plugins to extend loader() or customise its output.

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

export const source = loader({
  plugins: [
    {
      transformStorage: ({ storage }) => {},
      transformPageTree: {
        // ...
      },
    },
  ],
});

Storage

During the process, your input source files will be parsed and form a virtual storage in memory.

To perform virtual file-system operations before processing, you can hook transformStorage.

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

export const source = loader({
  plugins: [
    {
      transformStorage: ({ storage }) => {
        storage.read('...');
      },
      transformPageTree: {
        // ...
      },
    },
  ],
});

Page Tree

The page tree is generated from your file system, some unnecessary information (e.g. unused frontmatter properties) will be filtered.

You can customise it using the transformPageTree, such as attaching custom properties to nodes, or customising the display name of pages.

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

export const source = loader({
  plugins: [
    {
      transformPageTree: {
        file(node, file) {
          // access the original (unfiltered) file data
          if (file) console.log(this.storage.read(file));

          // modify nodes
          node.name = <>Some JSX Nodes here</>;
          return node;
        },
      },
    },
  ],
});

Custom Source

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

Since Source API doesn't rely on file system, file paths only allow special paths like file.mdx and content/file.mdx.

Paths like ./file.mdx and D://content/file.mdx are not allowed

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

export function createMySource(): Source<{
  metaData: { title: string; pages: string[] }; // Your custom type
  pageData: { title: string; description: string }; // Your custom type
}> {
  return {
    files: [
      {
        type: 'page',
        path: 'folder/index.mdx',
        data: {
          title: 'Hello World',
          description: 'A sample page',
          // ...
        },
      },
      {
        type: 'meta',
        path: 'meta.json',
        data: {
          title: 'Docs',
          pages: ['folder'],
          // ...
        },
      },
    ],
  };
}

On this page