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 とほぼ同じです。
Macro でコレクションを定義する場合でも、グローバルオプションやプラグインの設定用に source.config.ts を引き続き使用できます。
モノレポ
複数のアプリ間でコレクションを共有するには、ワークスペースパッケージでコレクションを宣言します。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,
});ブラウザ
Macro コレクションはブラウザでも動作します。クライアントコンポーネントでコレクションをインポートし、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>
);
}パスパラメータを持つページでは、ローダーから params を渡します:docs.getPage(page.path, page.params)。
ブラウザは、docs のインポート元のモジュール全体を実行します。loader() に openapi.staticSource() のようなサーバー専用の
ソースが含まれる場合は、コレクションを別のモジュール (例:
lib/collections.ts) で定義し、そこからインポートしてください。
非同期コレクション
async を有効にすると、事前にバンドルされるのはフロントマターのみとなり、コンテンツはオンデマンドで取得されます。
body も同じように使えますが、コンテンツが利用可能になるまでサスペンドする点が異なります。この挙動は、次の 2 つの追加メソッドで制御できます。
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 で対象を絞り込んでください。
制約
Macro の呼び出しは静的にコンパイルされます。以下のルールに注意してください。
-
各呼び出しはトップレベルの
constに代入してください(変数名によってコレクションが識別されます):// ✓ const docs = defineDocs({ dir: 'content/docs' }); // ✗ サポートされていません export function create() { return defineDocs({ dir: 'content/docs' }); } -
コンテンツのバンドル方法に関わるオプション(
dir、files、async)は、静的に解析できる値(文字列または真偽値のリテラル)にする必要があります。動的なロジックは、schemaやmdxOptionsなどのオプション側に記述してください。 -
dynamicコレクションは、Macro API ではまだサポートされていません。遅延読み込みにはasyncの使用をおすすめします。 -
fumadocs-mdx/macroからの再エクスポートはサポートされていません。
How is this guide?
