加载器 API

它做什么？

🌐 What it does?

loader() 提供了一个接口，供 Fumadocs 与不同的内容来源进行整合。

• 生成页面别名和页面结构。
• 为每个页面分配 URL。
• 输出有用的工具以便与内容交互。

使用

🌐 Usage

你可以将其与诸如 Fumadocs MDX 之类的内容源一起使用，详情见 source。

🌐 You can use it with content sources like Fumadocs MDX, see source for details.

import { loader } from 'fumadocs-core/source';
import { docs } from 'fumadocs-mdx:collections/server';

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

网址

🌐 URL

你可以覆盖基础 URL，或为每个页面指定一个生成 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('/');
  },
});

别名

🌐 Slugs

定义一个自定义函数来从页面文件生成短标签。

🌐 Define a custom function to generate slugs from page files.

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

loader({
  slugs(file) {
    console.log(file.path, file.data);
    // or return `undefined` to fallback to default value
    return ['my', 'slug'];
  },
});

图标

🌐 Icons

加载由页面和元文件指定的图标属性。

🌐 Load the icon property specified by page 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

将 i18n 配置传递给加载器。

🌐 Pass the i18n config to loader.

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.

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

🌐 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.getPageTree();

// with i18n
source.getPageTree('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

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

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

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();

客户端 API

🌐 Client API

在 RSC 环境中使用 Loader API 效果最佳，这允许在服务器与客户端之间传递 JSX 节点。

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

对于非 RSC 环境，它提供了一个微小的序列化层。

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

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

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

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