loader()

使用方法

loader() 为 Fumadocs 提供了一个接口，用于与基于文件系统的内容源集成。

它做什么？

生成页面 slug 和页面树。
为每个页面分配 URL。
输出有用的实用工具来与内容交互。

它不依赖于真实的 file system（零 node:fs 使用），也允许虚拟存储。

您可以使用它与内置的内容源如 Fumadocs MDX 一起使用。

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

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

URL

您可以覆盖基础 URL，或指定一个函数为每个页面生成 URL。

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

加载页面和元文件中指定的 icon 属性。

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 配置传递给 loader。

lib/source.ts

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

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

有了 i18n 启用，loader 将为每个 locale 生成一个页面树。

如果页面缺少翻译，它会回退到 fallbackLanguage。

输出

loader 输出一个 source 对象。

获取页面

使用 slugs 获取页面。

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

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

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

获取页面列表

获取 locale 可用页面的列表。

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

// from default locale
source.getPages();

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

页面树

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

// without i18n
source.pageTree;

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

从节点获取

页面树节点包含对原始文件路径的引用。您可以从树节点中找到它们的原始页面或元文件。

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

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

Params

一个用于 Next.js generateStaticParams 的函数来生成输出。生成的参数名称将是 slug: string[] 和 lang: string (仅 i18n)。

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

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

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

语言条目

获取可用语言及其页面。

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

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

深入探讨

如前所述，Source API 不依赖于真实的文件系统。在过程中，您的输入源文件将被解析并形成一个虚拟存储，以避免不同 OS 之间的不一致行为。

Transformer

为了在处理之前执行虚拟文件系统操作，您可以添加一个 transformer。

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

loader({
  transformers: [
    ({ storage }) => {
      storage.makeDir();
    },
  ],
});

页面树

页面树是从您的文件系统生成的，一些不必要的信息（例如未使用的 frontmatter 属性）将被过滤。

您可以使用 pageTree 选项自定义它，例如将自定义属性附加到节点，或自定义页面的显示名称。

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

loader({
  pageTree: {
    transformers: [
      {
        file(node, file) {
          // you can access its file information
          if (file) console.log(file, this.storage.read(file));

          // JSX nodes are allowed
          node.name = <>Some JSX Nodes here</>;

          return node;
        },
      },
    ],
  },
});

自定义源

要插入您自己的内容源，创建一个 Source 对象。

由于 Source API 不依赖于文件系统，文件路径只允许特殊的路径如 file.mdx 和 content/file.mdx。

不允许像 ./file.mdx 和 D://content/file.mdx 这样的路径

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',
          // ...
        },
      },
      {
        type: 'meta',
        path: 'meta.json',
        data: {
          title: 'Docs',
          pages: ['folder'],
          // ...
        },
      },
    ],
  };
}

On this page