ローカル Markdown

はじめにアンカーリンクをコピー

@fumadocs/local-md は、ローカルの Markdown/MDX ファイル向けのコンテンツソースです。設計上バンドラーを使用しないため、ランタイムのみで完結して動作します。

MDX Remote と比べると、ローカルファイルに特化している分、パイプラインのより多くの部分(フロントマター、meta ファイル、検索インデックスの作成)を担います。

Fumadocs MDX と比べると、型生成やバンドラーなしで動作しますが、ビルド時の画像最適化は無効になります。

制限事項アンカーリンクをコピー

• ビルド時の画像最適化には対応していません。
• MDX ファイル内ではインポート/エクスポートを使用できませんが、レンダリング時にコンポーネントを渡すことはできます。

セットアップアンカーリンクをコピー

パッケージをインストールします。

npm install @fumadocs/local-md shiki

localMd インスタンスを作成し、Fumadocs に接続します。

import { dynamicLoader } from 'fumadocs-core/source';
import { localMd } from '@fumadocs/local-md';

const docs = localMd({
  dir: 'content/docs',
  // オプション
});

const docsLoader = dynamicLoader(docs.dynamicSource(), {
  baseUrl: '/docs',
});

export async function getSource() {
  return docsLoader.get();
}

スキーマアンカーリンクをコピー

frontmatterSchema と metaSchema を渡すと、バリデーションに使用するスキーマをカスタマイズできます。

import { localMd } from '@fumadocs/local-md';
import { pageSchema, metaSchema } from 'fumadocs-core/source/schema';

const docs = localMd({
  dir: 'content/docs',
  frontmatterSchema: pageSchema.extend({
    // ...
  }),
  metaSchema: metaSchema.extend({
    // ...
  }),
});

使い方アンカーリンクをコピー

getSource() は通常のコンテンツローダーを返します。各ページには page.data.load() があり、ページをコンパイルしてレンダラーを返します。

ページ内でレンダリングします。

import { getSource } from '@/lib/source';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';

export default async function Layout({ children }: LayoutProps<'/docs'>) {
  const source = await getSource();

  return <DocsLayout tree={source.getPageTree()}>{children}</DocsLayout>;
}

インクルードアンカーリンクをコピー

<include> はデフォルトで有効になっています。

<include>../shared/note.md</include>

Markdown ファイルでは、remark-directive を設定したうえで ::include[../shared/note.md] ディレクティブを使用します。

import remarkDirective from 'remark-directive';

const docs = localMd({
  dir: 'content/docs',
  mdOptions: { remarkPlugins: [remarkDirective] },
});

ホットリロードアンカーリンクをコピー

@fumadocs/local-md はランタイムにファイルを読み込むため、デフォルトではファイルの変更は監視されません。

開発中は、同梱の開発サーバーをアプリと並行して実行してください。開発サーバーは単一のプロセスでファイルを監視し、変更を WebSocket 経由でブロードキャストするため、Next.js が複数のワーカーを実行する場合でも動作します。

{
  "scripts": {
    "dev": "local-md dev -- next dev"
  }
}

ソースを開発サーバーに接続します。

import { watchWithDevServer } from '@fumadocs/local-md/dev/ws';

if (process.env.NODE_ENV === 'development') {
  void watchWithDevServer(docs);
}

コマンドが環境変数経由で URL を公開するため、設定は不要です。サーバーを自分で起動する場合は URL を明示的に渡してください。ポートを変更するには -p を使用します。

void watchWithDevServer(docs, { url: 'ws://127.0.0.1:8000/_fumadocs_local_md' });

これによりサーバー上のソースは無効化されますが、ブラウザ側では Next.js がレンダリング済みのページを保持したままです。ページも更新されるように、ルートレイアウトで <DevClient /> をレンダリングしてください。

import { DevClient } from '@fumadocs/local-md/dev/react-client';

export function RootLayout({ children }) {
  return (
    <RootProvider>
      <DevClient />
      {children}
    </RootProvider>
  );
}

Markdown や MDX ファイル (それらがインクルードするファイルを含む) が変更されると、ソースがリロードされます。独自のウォッチャーを組み込む場合は、docs.dir と docs.onDependency() に渡されたファイルを監視し、ファイルの変更時に docs.invalidateFile(path) を呼び出してください。

JavaScript エンジンアンカーリンクをコピー

MDX ファイル(*.mdx)は new Function で実行されるため、eval() が禁止されている環境(Cloudflare Workers など)では動作しません。

Markdown ファイル(*.md)は eval() を使わずに構文木からレンダリングされます。プラグインが生成した JSX は、組み込みの仮想 JavaScript エンジンで評価されます。このエンジンは rendererOptions.executor で差し替えられます。

再検証を無効にするアンカーリンクをコピー

staticSource() は、再検証を行わない一度きりのスナップショットを返します。dynamicLoader() ではなく loader() と組み合わせて使用します：

import { loader } from 'fumadocs-core/source';
import { localMd } from '@fumadocs/local-md';

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

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

Fumadocs MDX からの移行アンカーリンクをコピー

移行するには、Fumadocs MDX のセットアップを @fumadocs/local-md のセットアップに置き換えます。

移行前アンカーリンクをコピー

import { defineDocs, defineConfig } from 'fumadocs-mdx/config';

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

export default defineConfig();

移行後アンカーリンクをコピー

import { dynamicLoader } from 'fumadocs-core/source';
import { localMd } from '@fumadocs/local-md';

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

const docsLoader = dynamicLoader(docs.dynamicSource(), {
  baseUrl: '/docs',
});

export async function getSource() {
  return docsLoader.get();
}

続いて、次の作業を行います。

• source.config.ts を削除します。
• next.config.mjs から createMDX() を削除します。
• collections/server のインポートを、localMd() から作成したローダーに置き換えます。
• ホットリロードを設定します。

最後に、source オブジェクトを参照している箇所を getSource() を使うように書き換えます。

import { getSource } from '@/lib/source';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';

export default async function Layout({ children }: LayoutProps<'/docs'>) {
  return <DocsLayout tree={source.getPageTree()}>{children}</DocsLayout>;

  const docs = await getSource();
  return <DocsLayout tree={docs.getPageTree()}>{children}</DocsLayout>;
}

ページデータの API も変わります。

const page = source.getPage(['...']);

// タイトルと説明
page.data.title;

// カスタムのフロントマタープロパティ
page.data.full;

// getText() API
await page.data.getText('processed');

// コンパイル済みのプロパティ:
page.data.structuredData;
page.data.toc;
return (
  <div>
    <page.data.body components={{}} />
  </div>
);