跳至內容
Fumadocs

Macro API

使用 fumadocs-mdx/macro 在您的應用程式中定義集合。

概覽

透過 fumadocs-mdx/macro,直接在您的應用程式模組中宣告集合。

打包工具 (或執行階段載入器) 會將 defineDocs / defineCollections 編譯為內容檔案的匯入陳述式。

  • 無需產生程式碼。
  • 無需 source.config.ts。

使用方式

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

export const docs = defineDocs({
  dir: 'content/docs',
});

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

集合選項大致與 config API 相同。

使用巨集定義集合時,您仍可保留 source.config.ts,用來設定全域選項與外掛。

Monorepo

若要在多個應用程式之間共用集合,請在工作區套件中宣告這些集合。dir 的路徑是相對於匯入該集合的應用程式而言,因此每個應用程式都會載入各自的內容。

import { defineCollections } from 'fumadocs-mdx/macro';
import { pageSchema } from 'fumadocs-core/source/schema';

export const blog = defineCollections({
  type: 'doc',
  dir: 'content/blog',
  schema: pageSchema,
});

瀏覽器

巨集集合同樣可以在瀏覽器中使用。只要在用戶端元件中匯入集合,再透過 body 算繪項目即可,不需要用戶端載入器。

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

export default function Page({ path }: { path: string }) {
  const page = docs.getPage(path);
  if (!page) return <div>Not Found</div>;

  const MDX = page.body;

  return (
    <div className="prose">
      <h1>{page.title}</h1>
      <MDX />
    </div>
  );
}

若頁面使用了路徑參數,請從載入器傳入其參數:docs.getPage(page.path, page.params)。

瀏覽器會執行您匯入 docs 的那個模組的全部內容。若您的 loader() 含有僅限伺服器的 來源 (例如 openapi.staticSource()) ,請在另一個模組中定義集合 (例如 lib/collections.ts) ,再從該模組匯入。

Async 集合

啟用 async 後,只有 frontmatter 會預先打包,內容則會隨需擷取。

body 的運作方式相同,只是它會先暫停 (suspend) ,直到內容就緒為止。另有兩個方法可以控制這個行為:

  • preload() 會在算繪前先載入內容,讓 body 算繪時不必暫停。請在您的路由載入器中呼叫它。
  • load() 會回傳已載入的內容,例如 toc。它的 promise 會被快取,因此您可以在算繪期間呼叫它。
import { use } from 'react';
import { docs } from '@/lib/source';

// 在您的路由載入器中(React Router、TanStack Start)
export async function loader({ path }: { path: string }) {
  await docs.getPage(path)?.preload();
  return { path };
}

export default function Page({ path }: { path: string }) {
  const page = docs.getPage(path);
  if (!page) return <div>Not Found</div>;

  const { toc } = use(page.load());
  const MDX = page.body;

  return (
    <div className="prose">
      <h1>{page.title}</h1>
      <MDX />
    </div>
  );
}

由於內容採用延遲載入,除非您已預先載入,否則請用 <Suspense> 邊界包住頁面。

設定

Macro API 預設為啟用。傳入 macro 可限制哪些模組能使用它,傳入 false 則會將其停用。若使用 React Router 或 TanStack Start,請將其傳給 Vite 外掛。

next.config.mjs
import { createMDX } from 'fumadocs-mdx/next';

const withMDX = createMDX({
  macro: {
    // 相對於專案根目錄的 glob 模式
    include: ['lib/**/*.ts', 'lib/**/*.tsx'],
  },
  // 或完全停用:
  // macro: false,
});

預設情況下,所有 JS/TS 模組都會納入處理 (node_modules 一律排除) 。若您只想讓轉換套用在特定路徑上,請縮小 include 的範圍。

限制

巨集呼叫會以靜態方式編譯,請留意以下規則:

  • 將每個呼叫指派給頂層的 const (集合由變數名稱識別) :

    // ✓
    const docs = defineDocs({ dir: 'content/docs' });
    
    // ✗ 不支援
    export function create() {
      return defineDocs({ dir: 'content/docs' });
    }
  • 會影響內容打包方式的選項 (dir、files、async) 必須能夠靜態分析 (即字串/布林常值) 。動態邏輯請改放在 schema 或 mdxOptions 等選項中。

  • Macro API 目前尚不支援 dynamic 集合。如需延遲載入,建議改用 async。

  • 不支援從 fumadocs-mdx/macro 重新匯出。

How is this guide?