コンテンツへスキップ
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 とほぼ同じです。

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 プラグインに渡してください。

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 で対象を絞り込んでください。

制約

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?