コンテンツへスキップ
Fumadocs

AI と LLM

Fumadocs に AI 機能を組み込みます。

LLM向けのドキュメント

ドキュメントをMarkdown形式でLLMやAIエージェントに提供できます。

npx @fumadocs/cli feature llms

これにより、docs コレクションで処理済みの Markdown が有効になり、lib/source.ts に docsLlms が追加され、以下のファイルが配信されます。手動でセットアップする場合に備えて、生成されるファイルを以下に示します。

docsLlms

llms() は、ドキュメントを LLM 向けにレンダリングします。renderPage は、生のファイル内容ではなく処理済みのドキュメントをもとに、1 つのページを Markdown に変換します。

lib/source.ts
import { llms } from 'fumadocs-core/source';

export const docsLlms = llms(source, {
  renderPage: async (page) => `# ${page.data.title} (${page.url})

${await page.data.getText('processed')}`,
});
メソッド出力
index(lang?)ページツリーから構築される llms.txt インデックス
page(page)renderPage でレンダリングした単一ページ
full(lang?)renderPage でレンダリングした全ページを結合したもの
files()エージェント向けファイルのパス
serve(path)指定したパスにあるファイルのレスポンス

renderPage は必須です

page()、full()、files()、serve() は、renderPage を渡した場合にのみ利用できます。 コンテンツソースが Markdown をどのように公開しているかを、Fumadocs 側では把握できないためです。

renderPage はページの処理済み Markdown を読み込むため、includeProcessedMarkdown を有効にしてください。

source.config.ts
import { defineDocs } from 'fumadocs-mdx/config';

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

MDX コンポーネントは JSX 構文のまま出力されます。これらを Markdown 形式にレンダリングするには、MDX コンポーネントをページの props として渡してください。

@fumadocs/local-md のようなランタイムのコンテンツソースは、リクエスト時にオンデマンドで解決されます。その getSource を渡せば、CLI が同じファイルを生成します。

export const docsLlms = llms(getSource, {
  renderPage: (page) => `# ${page.data.title} (${page.url})

${page.data.content}`,
});

getSource を使用する場合、index() と indexNode() は文字列ではなく Promise を返します。

ファイル

CLIは、AIエージェント向けに次のファイルを配信します。

  • /llms.txt: ドキュメントのインデックスです。各ページのMarkdownへのリンクが含まれます。
  • /llms-full.txt: すべてのページのコンテンツです。
  • <page>.md: ページのMarkdownです(例: /docs/ui.md)。/ のページは /index.md になります。
  • <section>/llms-full.txt: セクションのコンテンツです(例: /docs/ui/llms-full.txt)。

下書きなど、特定のページをこれらのファイルから除外するには filter を渡します。除外したページも llms.txt には引き続き掲載され、HTMLページへのリンクになります。

lib/source.ts
export const docsLlms = llms(source, {
  filter: (page) => page.slugs[0] !== 'drafts',
  renderPage: async (page) => `# ${page.data.title}\n\n${await page.data.getText('processed')}`,
});

これらのファイルでは、renderUrl はリンク先のファイルのパス(ページの .md ファイルなど)を受け取ります。

ページの HTML を読み取るエージェントは、次のように <head> 内のリンクからそのページの Markdown を見つけます。

<link rel="alternate" type="text/markdown" href="/docs/ui.md" />

セクション

セクションとは、独自の llms-full.txt を持つページツリー内のフォルダーです。これにより、エージェントは大規模なドキュメントを部分ごとに読み込めます。デフォルトでは、すべてのルートフォルダーがセクションになります。llms.txt では、各フォルダーの行がそのセクションの llms-full.txt へのリンクになります。

どのフォルダーをセクションにするかを指定するには、section を渡します。この関数はフォルダーを受け取り、そのフォルダーがセクションかどうかを返します。

lib/source.ts
export const docsLlms = llms(source, {
  // index ページを持つすべてのフォルダー
  section: (folder) => folder.index !== undefined,
  renderPage: async (page) => `# ${page.data.title}\n\n${await page.data.getText('processed')}`,
});

大規模なサイトでは、セクションを折りたたむことで llms.txt を短く保てます。折りたたんだセクションは、llms.txt ではそのセクション専用の <section>/llms.txt への1つのリンクとして掲載され、セクション内のページはそのファイルに一覧表示されます。

lib/source.ts
export const docsLlms = llms(source, {
  section: (folder) => (folder.root ? { collapse: true } : false),
  renderPage: async (page) => `# ${page.data.title}\n\n${await page.data.getText('processed')}`,
});

セクションのファイルは、そのフォルダーのインデックスページの URL で配信されます。インデックスページがないフォルダーでは、代わりに配下のページの URL ディレクトリが使用されます。フォルダーグループのように 2 つのフォルダーが同じ URL を共有する場合は、{ asPath: '/docs/guides' } のように asPath を渡して、一方を別のパスで配信してください。

ルート

files() はファイルのパスを一覧で返し、serve(path) は指定したパスのファイルをレスポンスとして返します。そのため、各ルートではリクエストパスを serve() に渡すだけで済みます。

/llms.txt と /llms-full.txt はルートハンドラーで配信します。その他のファイルは app/docs/[[...slug]] と同じ階層に置かれるため、Next.js の設定でそれらのパスを /llms.mdx/[...path] ルートへリライトします。

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

export const revalidate = false;

export async function GET() {
  return (await docsLlms.serve('/llms.txt'))!;
}

serve() はファイルが存在しないパスに対して undefined を返すため、ミドルウェアはリクエストを後続の処理に渡せます。hideLocale: 'always' を指定した場合は URL にロケールが含まれないため、言語を serve() の第2引数、files() の第1引数として渡してください。

静的出力

output: 'export' を使用する場合、Next.js ではリライトが使えません。/llms.mdx/[...path] ルートが /llms.mdx/docs/ui.md のようなプレフィックス付きのパスでファイルを配信し、renderUrl で llms.txt 内のリンクをそのパスに向けます。

lib/source.ts
import { llms } from 'fumadocs-core/source';

export const docsLlms = llms(source, {
  renderPage: async (page) => `# ${page.data.title} (${page.url})

${await page.data.getText('processed')}`,
  // link to the files under `/llms.mdx`
  renderUrl: (item) => (/^\/.*\.(md|txt)$/.test(item.url) ? `/llms.mdx${item.url}` : item.url),
});

Accept

AIエージェントは Accept ヘッダーを使って Markdown をリクエストできます。

リクエストが Markdown を優先する場合は、ページの Markdown を返します。

proxy.ts
import { NextRequest, NextResponse } from 'next/server';
import { isMarkdownPreferred, rewritePath } from 'fumadocs-core/negotiation';

const { rewrite: rewriteDocs } = rewritePath('/docs{/*path}', '/llms.mdx/docs{/*path}.md');

export default function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;
  // `/docs/ui.md` のようなファイルは Next.js 設定の rewrites によって配信されます
  const result =
    isMarkdownPreferred(request) && !/\.(md|txt)$/.test(pathname) && rewriteDocs(pathname);

  if (result) {
    return NextResponse.rewrite(new URL(result, request.nextUrl), {
      headers: { Vary: 'Accept' }, 
    });
  }

  return NextResponse.next();
}

同じ URL に2種類の表現が存在することになるため、キャッシュの衝突を防ぐには、レスポンスに Vary: Accept を含める必要があります。

Next.js は App Router のページレスポンスから Vary を除去するため、ドキュメントページの HTML レスポンスにはこのヘッダーを 付与できません。共有キャッシュからドキュメントを配信している場合は、CDN 側で設定してください。

ページアクション

ページアクションを使うと、読者はページの Markdown をコピーしたり、ページを AI アプリで開いたりできます。ページアクションはページの .md ファイルを読み込みます。

AI ページアクション

ドキュメントページでレンダリングします。

import { MarkdownCopyButton, ViewOptionsPopover } from 'fumadocs-ui/layouts/docs/page';

const markdownUrl = `${page.url}.md`;

<div className="flex flex-row gap-2 items-center border-b pt-2 pb-6">
  <MarkdownCopyButton markdownUrl={markdownUrl} />
  <ViewOptionsPopover
    markdownUrl={markdownUrl}
    githubUrl={`https://github.com/${owner}/${repo}/blob/main/content/docs/${encodeURI(page.path)}`}
  />
</div>;

静的エクスポートの場合は、URL が `/llms.mdx${page.url}.md` になります。

MCP サーバー

MCP サーバーを介してドキュメントをAIエージェントに公開できます。ページの一覧表示、検索、読み取りを行うツールも備えています。

npx @fumadocs/cli feature mcp

上記の LLM ルート に加えて、Streamable HTTP トランスポートを使用する /api/mcp ルートが作成されます。

ツールは fumadocs-core/mcp から提供されます。

app/api/mcp/route.ts
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import { registerSearchTool, registerSourceTools } from 'fumadocs-core/mcp';
import { createFromSource } from 'fumadocs-core/search/server';
import { docsLlms, source } from '@/lib/source';

const handler = createMcpHandler(() => {
  const mcp = new McpServer(
    {
      name: 'docs',
      version: '1.0.0',
    },
    // the tools never change, a stream to watch them would hold a serverless function open
    { capabilities: { tools: { listChanged: false } } },
  );

  registerSourceTools(mcp, source, docsLlms);
  registerSearchTool(mcp, createFromSource(source));

  return mcp;
});

export async function GET(request: Request) {
  return handler.fetch(request);
}

export async function POST(request: Request) {
  return handler.fetch(request);
}

export async function DELETE(request: Request) {
  return handler.fetch(request);
}

エージェントを接続するには、次のようにします。

{
  "mcpServers": {
    "docs": { "url": "https://your-site.com/api/mcp" }
  }
}

WebMCP

実験的機能

WebMCP は初期段階の Web 標準で、 Chrome 149 以降で #enable-webmcp-testing フラグを有効にするか、オリジントライアルを通じて利用できます。API は今後 変更される可能性があります。

前述の MCP サーバーがサイトに接続してくるエージェント向けであるのに対し、WebMCP は読者が閲覧中のページ上で、ブラウザに搭載された AIエージェント にツールを公開します。

npx @fumadocs/cli feature webmcp

LLM ルートをベースに WebMCP コンポーネントを作成します。このコンポーネントは <RootProvider /> の内側でレンダリングしてください。

  • search_docs は検索 API ルートにクエリを送信します。fetchClient は他のクライアントに置き換えることもできます。
  • read_page は、/docs/page.md からページの Markdown を取得します。

AIに質問

AI Search

Fumadocs CLI を使用して、AI チャットダイアログをインストールできます。

npx @fumadocs/cli add ai/openrouter

Vercel AI SDK を使用して OpenRouter 向けに自動で設定され、AI 用の /search ツールも含まれます。

/api/chat ルートを更新すると、他のモデルも使用できます。

Fumadocs は AI モデルを提供しません。使用するモデルはご自身で用意してください。

AI モデルには、上記で生成した llms-full.txt ファイルを利用できます。また、サードパーティのソリューションと組み合わせれば、より多様な情報源を活用することもできます。

Docs レイアウトは、aiChat オプションをもとにチャットをレンダリングします。このオプションはクライアントの状態を受け取るため、レイアウト用のクライアントコンポーネントを作成し、元のレイアウトの代わりに使用してください。

'use client';
// Notebook、Glass、Spacious レイアウトも使用できます
import { DocsLayout as Layout, type DocsLayoutProps } from 'fumadocs-ui/layouts/docs';
// インストールしたコンポーネント
import { AIChat, AIChatPanel, useAIChat } from './search';

export function DocsLayout(props: DocsLayoutProps) {
  return (
    <AIChat>
      <ChatLayout {...props} />
    </AIChat>
  );
}

function ChatLayout(props: DocsLayoutProps) {
  const { open, setOpen } = useAIChat();

  return (
    <Layout
      {...props}
      aiChat={{ open, onOpenChange: setOpen, panel: <AIChatPanel />, trigger: true }}
    />
  );
}

レイアウトのオプションはクライアントコンポーネントに渡されるため、シリアライズ可能な値にする必要があります。

How is this guide?