# Fumadocs Core (the core library of Fumadocs): Loader API
URL: /docs/headless/source-api
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/source-api/index.mdx

Turn content sources into a unified interface

## What it does? [#what-it-does]

`loader()` provides an interface for Fumadocs to integrate with different content sources.

- Generate [page slugs and page tree](/docs/headless/page-conventions).
- Assign URL to each page.
- Output useful utilities to interact with content.

<Callout type="warn" title="Important to Know">
- `loader()` is a server-side API, not a build-time magic or browser compatible API.
- It uses in-memory storage, the files are passed from your content sources.
</Callout>

## Usage [#usage]

You can use it with content sources like Fumadocs MDX, see [`source`](/docs/headless/source-api/source) for details.

```ts
import { loader } from 'fumadocs-core/source';
import { docs } from 'collections/server';

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

### URL [#url]

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

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

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

### Slugs [#slugs]

Define a custom function to generate slugs from page files.

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

loader({
  slugs(file, next) {
    console.log(file.path, file.data);
    // you can build on the default slugs with `next()`
    if (file.path.startsWith('blog/')) return ['blog', ...next()];
    // or return `undefined` to fallback to default value
    return ['my', 'slug'];
  },
});
```

### Icons [#icons]

Load the [icon](/docs/headless/page-conventions#icons) property specified by page and meta files.

```ts
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 [#i18n]

Pass the `i18n` config to loader.

```ts title="lib/source.ts"
import { i18n } from '@/lib/i18n';
import { loader } from 'fumadocs-core/source';

export const source = loader({
  i18n, // [!code highlight]
});
```

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

If translations are missing for a page, it fallbacks to [`fallbackLanguage`](/docs/headless/internationalization/config#fallback-language).

## Output [#output]

It outputs a content loader instance.

### Get Page [#get-page]

Get page with slugs.

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

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

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

#### Custom Props [#custom-props]

Pass props to the content of a page, like a version that the reader picks. The content reads them as `props`, like [path params](/docs/headless/page-conventions#path-params):

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

const page = source.getPage(['slug', 'of', 'page'], {
  props: { version: 'v2' },
  // with i18n
  language: 'locale',
});
```

The page data is generated with these props, including the content and the table of contents. MDX components are props too. Pass them when processed Markdown should render your components:

```ts
import { getMDXComponents } from '@/components/mdx';

const page = source.getPage(['slug', 'of', 'page'], {
  props: { components: getMDXComponents() },
});
const markdown = await page.data.getText('processed');
```

<Callout title="Good to Know">
Search and LLM routes read pages from `getPages()`, which only have their path params. A variant that search or LLMs should see must be a path param.
</Callout>

### Get Pages [#get-pages]

Get a list of page available for locale.

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

// from any locale
source.getPages();

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

### Page Tree [#page-tree]

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

// without i18n
source.getPageTree();

// with i18n
source.getPageTree('locale');
```

### Get from Node [#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.

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

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

### Params [#params]

Generate the path params of every page, for pre-rendering pages.
The generated parameter names will be `slug: string[]` and `lang: string` (i18n only).

```ts tab="Next.js" title="app/docs/[[...slug]]/page.tsx"
import { source } from '@/lib/source';

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

```ts tab="Waku" title="src/pages/docs/[...slugs].tsx"
import { source } from '@/lib/source';

export async function getConfig() {
  const pages = source
    .generateParams()
    .map((item) => (item.lang ? [item.lang, ...item.slug] : item.slug));

  return {
    render: 'static' as const,
    staticPaths: pages,
  } as const;
}
```

```astro tab="Astro" title="src/pages/docs/[...slug].astro"
---
import type { GetStaticPaths } from 'astro';
import { source } from '@/lib/source';

export const prerender = true;

export const getStaticPaths = (() => {
  return source.getPages().map((page) => ({
    params: { slug: decodeURI(page.slugs.join('/')) || undefined },
    props: { page },
  }));
}) satisfies GetStaticPaths;
---
```

React Router and TanStack Start pre-render by URL. List the `url` of `source.getPages()` instead.

### Language Entries [#language-entries]

Get available languages and its pages.

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

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

## Client API [#client-api]

Loader API is best when used in RSC environments, which allows passing JSX nodes across the server-client boundary.

For non-RSC environments, it provides a tiny serialization layer.

```ts tab="Server"
import { source } from '@/lib/source';

// where you pass loader data
async function loader() {
  const pageTree = source.getPageTree();

  return {
    pageTree: await source.serializePageTree(pageTree),
  };
}
```

```tsx tab="Client"
import { useFumadocsLoader } from 'fumadocs-core/source/client';

function MyComponent() {
  // `useLoaderData()` receives loader data (provided by your React framework)
  const { pageTree, ...data } = useFumadocsLoader(useLoaderData());

  // now render it (e.g. via Fumadocs UI)
  return <DocsLayout tree={pageTree}>...</DocsLayout>;
}
```

## Dynamic Loader [#dynamic-loader]

`dynamicLoader()` provides extra revalidation functionality to content sources, you should use it with a [dynamic source](/docs/headless/source-api/source#dynamic-source).

```ts
import { dynamicLoader } from 'fumadocs-core/source';
import { createMySource } from './my-source';

const source = dynamicLoader(createMySource(), {
  baseUrl: '/docs',
});

export async function getSource() {
  return source.get();
}
```

When you call `await source.get()`, it returns a normal content loader object:

```ts
const docs = await getSource();

const page = docs.getPage(['...']);
```

### Revalidation [#revalidation]

Dynamic sources are cached by the loader.

If your source changes over time, call `invalidate()` to clear the cache, or `revalidate()` to update the cache:

```ts
source.invalidate();

await source.revalidate();
```

For [multi-source](/docs/headless/source-api/source#multiple-sources) setups, you can invalidate/revalidate a specific source:

```ts
source.invalidate('docs');

await source.revalidate('docs');
```