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 外掛。
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等選項中。 -
不支援從
fumadocs-mdx/macro重新匯出。
How is this guide?
