Markdown レンダリング

概要アンカーリンクをコピー

fumadocs-core/server は、React サーバーコンポーネントを Markdown ドキュメントとしてレンダリングします。

import { renderToMarkdown } from 'fumadocs-core/server';

const text = await renderToMarkdown(
  <div>
    <h2>Hello World</h2>
    <p>
      Some <b>rich</b> content.
    </p>
  </div>,
);

これは Remark LLMs がエクスポートするコンポーネントの内部で使用されており、Markdown として配信したいサーバーレンダリングされたコンテンツであれば、どのようなものにも使用できます。

asMarkdownアンカーリンクをコピー

各コンポーネントは、それぞれ独自の Markdown 表現を定義します。レンダリング中に asMarkdown() を呼び出すことで、この機能を有効化 (オプトイン) できます。asMarkdown() は、コンポーネントが Markdown にレンダリングされている場合にターゲットを返し、そのときコンポーネントが返す HTML 要素は Markdown に変換されます。

import { asMarkdown, md } from 'fumadocs-core/server';

function Callout({ title, children }) {
  if (asMarkdown()) return md.linePrefix('> ')`**${title}**\n${children}`;

  return <div className="...">...</div>;
}

これを一度も呼び出さないコンポーネントは、次のように props を保持したまま JSX 構文として残ります。

<Tabs items={['a', 'b']}>...</Tabs>

これには、サーバー上では実行されないクライアントコンポーネントも含まれます。

ターゲットアンカーリンクをコピー

ツリーはターゲットに応じてレンダリングされます。ターゲットは renderToMarkdown() の target オプションで指定します。

• markdown (デフォルト) : エージェント向けのドキュメントです。
• search: 検索レコードのテキストです。リンクのテキストは含まれますが、画像やコードブロックは含まれません。また、Markdown 形式を持たないコンポーネントは、テキストの props を持つ HTML タグとして出力されます。

これらのルールは、<a href> のようにコンポーネントが返す要素に適用されます。md テンプレート内にテキストとして書かれたリンクは、検索でもリンク先が残ります。そのため、要素を返すか、ターゲットを確認してください。

asMarkdown() はターゲットを返すため、コンポーネントは検索インデックス向けよりも多くの情報をエージェントに提供できます。

import { asMarkdown, md } from 'fumadocs-core/server';

function Version({ name, released }) {
  const target = asMarkdown();
  if (target === 'search') return name;
  if (target) return md`${name} (released ${released})`;

  return <span title={released}>{name}</span>;
}

mdアンカーリンクをコピー

Markdown 出力用のタグ付きテンプレートです。埋め込む値には、文字列、React ノード、Promise、またはそれらの配列を指定できます。children を加工する前に文字列化したい場合に使用します。

コンテンツをブロックとして返すバリアントが 2 つあります。

• md.linePrefix(prefix): すべての行の先頭にプレフィックスを付けます(例: 引用ブロックの場合は '> ')。
• md.indent(size): すべての行をインデントします。

renderRouteアンカーリンクをコピー

ページ要素を Markdown にレンダリングします。そのコンポーネントが asMarkdown() を呼び出していない場合は undefined を返します。

import { renderRoute } from 'fumadocs-core/server';

const text = await renderRoute(<Page params={params} />);

ルートの Markdown 版を配信する場合に便利です。オプトインしたページは Markdown を生成し、それ以外のページは undefined を返すため、404 を返したり別のソースにフォールバックしたりできます。