Fumadocs に CMS を導入する

既存の Fumadocs ドキュメントに Prosefly を導入し、MDX、対応するページ属性、標準ページリストを管理します。サイトの表示は、これまでのアプリケーションが担当します。

リポジトリ、コレクション、公開方法はオーナーまたは管理者が設定します。執筆者は Git コマンドを使わず、エディターで下書きを保存できます。アプリケーションのフレームワークやホスティングを変更する必要はありません。

1. ドキュメントのソースを確認する

ドキュメントの定義と MDX ファイルのディレクトリを確認します。標準的な設定例です。

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

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

この例では、ページは content/docs/index.mdx と content/docs/getting-started.mdx です。サイトの標準ローダーは、docs.toFumadocsSource() を通じて同じドキュメントソースを使います。

lib/source または src/lib/source 内で fumadocs-mdx/macro を使う、対応したインラインの defineDocs() 定義も読み取れます。ディレクトリ、schema、ローダーは静的に読み取れる必要があり、ファイル名だけでコレクションは決まりません。動作している既存の設定を維持し、別のアプリケーションの設定に置き換えないでください。

2. リポジトリを接続してコレクションを確認する

組織設定 → リポジトリから GitHub を接続し、対象ブランチをスキャンします。アカウント連携と GitHub App の認証は GitHub の接続をご覧ください。

アプリケーションのルート、コンテンツディレクトリ、文書コレクション、エディターのプロファイルを確認します。フィールドと対応する標準ナビゲーションの紐付けを確認して、コンテンツスペースを確定します。インデックス作成後に文書を開いてください。

schema で変更していなければ、defineDocs() は Title、Description、Icon、Full などの標準ページ属性を提供します。一部は More properties に表示されます。独自の文書コレクションでは、その対応 schema が使われます。ナビゲーションのメタデータや翻訳用 JSON ファイルを MDX 文書として取り込むことはありません。

3. MDX と対応コンポーネントを編集する

Content から文書を開きます。Markdown をビジュアル編集し、ページ属性を変更できます。対応する Fumadocs のコールアウト、タブ、ステップ、アコーディオンも編集できます。専用の操作がない独自コンポーネントや式には Source を使います。

Fumadocs 専用の操作は Fumadocs エディターのサンプルで試せます。登録不要で、再読み込みすると内容がリセットされます。リポジトリを接続したコンテンツスペースでは、公開するまで下書きが保存されます。

4. meta.json でページ順を管理する

Navigation パネルは、確認済みの紐付けを通じて文書コレクション、ローダー、対応する meta.json のページリストを扱います。上の2ページに対する明示的なリストの例です。

{
  "title": "Documentation",
  "pages": ["index", "getting-started"]
}

Navigation を開き、対応項目を並べ替えたり、未掲載の文書を既存の編集可能なリストに配置したりします。保存完了を待ち、文書と、同じディレクトリや上位ディレクトリで変更される meta.json を一緒に確認してください。

単一の文書ソース、静的なローダーオプション、読み取り可能なページ配列で利用できます。複数ソースの統合、API ページ生成、独自の実行時プラグイン、言語別の meta ファイルを使う場合は、本文のみの公開が必要になることがあります。その場合、ページはナビゲーションリストに追加されません。

5. 公開方法を設定し、差分を確認する

オーナーまたは管理者がコンテンツスペースの公開方法を選びます。次の画面は共通の公開設定で、Fumadocs でも同じ方法を使います。

公開前レビューで、MDX のパス、ページ属性、変更された meta.json の差分を確認します。Commit は対象ブランチへ書き込み、Pull request は確認済みの変更を含むブランチと PR を作成します。PR を使う場合は、マージ後に対象ブランチとサイトの更新を確認してください。

公開ファイルのビルドとデプロイは、既存の Fumadocs アプリケーションが担当します。Prosefly はそのアプリケーションを実行しません。ビルド後に、サイトの本文とナビゲーションを確認します。

ナビゲーションを編集できない場合

紐付けられた文書ソースがサイトと同じか、ローダーオプションと meta.json リストが静的に読み取れるかを確認します。コレクション設定で検出結果を確認してください。Prosefly の外で設定を変更した後は、再スキャンして紐付けを確認し直します。実行時に生成されるナビゲーションを標準の紐付けで編集できない場合は、本文のみの公開を選べます。

次は Fumadocs 向け CMS の紹介、製品ドキュメントの管理、ビジュアルエディター、Fumadocs Collections の公式ドキュメントをご覧ください。