moai-library-nextra

クイックリファレンス

目的：Nextra と Next.js を使って、プロフェッショナルなドキュメントサイトを構築します。

Nextra の利点：

• Markdown と JSX をシームレスに統合した、設定不要の MDX
• ファイルシステムベースのルーティングと、自動的なルート生成
• コード分割とプリフェッチによるパフォーマンス最適化
• プラグイン対応でカスタマイズ可能なテーマシステム
• 組み込みの国際化サポート

主要なファイル：

• pages ディレクトリには、MDX 形式のドキュメントページが含まれます
• theme.config.tsx ファイルには、サイトの設定が含まれます
• _meta.js ファイルは、ナビゲーション構造を制御します

実装ガイド

機能

このスキルでは、Nextra 3.x および 4.x のドキュメントフレームワークのアーキテクチャパターン、最適な設定による Next.js 14 および 15 との統合、theme.config.tsx または Layout の props によるテーマのカスタマイズ、FlexSearch との統合による高度な検索、国際化サポート、React コンポーネントを利用した MDX コンテンツ、さらに Turbopack との互換性を備えた Nextra 4.x の App Router サポートを扱います。

使用する場面

最新の React 機能を使ってドキュメントサイトを構築する場合、高度な検索機能を備えたナレッジベースを作成する場合、多言語ドキュメントポータルを開発する場合、カスタムのドキュメントテーマを実装する場合、または技術ドキュメントにインタラクティブなサンプルを組み込む場合に、このスキルを使用します。

プロジェクトのセットアップ

Nextra のドキュメントサイトを初期化するには、npx で docs テンプレートを指定し、create-nextra-app コマンドを使用します。生成されるプロジェクト構成には、カスタム App コンポーネントファイル、ホームページ用の index MDX ファイル、およびドキュメントセクション用のサブディレクトリを含む pages ディレクトリが含まれます。各セクションには、コンテンツ用の MDX ファイルとナビゲーション設定用の _meta.json ファイルが含まれます。

テーマの設定

theme.config.tsx ファイルは、いくつかの主要なプロパティを持つ設定オブジェクトをエクスポートします。logo プロパティは、サイトのブランディング要素を定義します。project プロパティには、プロジェクトのリポジトリへのリンクが含まれます。docsRepositoryBase プロパティは、編集リンク機能のベース URL を指定します。useNextSeoProps 関数は、タイトルテンプレートを含む SEO 設定を返します。

重要な設定オプションには、ロゴと logoLink のブランディング設定、プロジェクトリンクとリポジトリのベース URL のナビゲーション設定、デフォルトの折りたたみレベルと切り替えボタンの表示に関するサイドバー設定、「トップへ戻る」機能を含む目次設定、カスタムのフッターテキストに関するフッター設定があります。

ナビゲーション構造

_meta.js ファイルは、サイドバーメニューの順序と表示名を制御します。各ファイルはデフォルトオブジェクトをエクスポートし、そのキーはファイル名またはディレクトリ名、値は表示ラベルを表します。特殊な項目として、キーにハイフン3つ、値に空文字列を使った区切り線があり、外部リンクは title、href、newWindow プロパティを含むネストされたオブジェクトで設定できます。

MDX コンテンツと JSX の統合

Nextra では、MDX ファイル内で Markdown と React コンポーネントを直接混在させられます。コンポーネントはファイルの先頭でインポートし、Markdown コンテンツ内でインラインに使用できます。カスタムコンポーネントは、MDX ファイル内で定義してエクスポートすることもできます。nextra/components の Callout コンポーネントは、注記、警告、ヒント用のスタイル付きコールアウトボックスを提供します。

検索と SEO の最適化

テーマ設定では、プレースホルダーテキストをカスタマイズできる組み込み検索がサポートされています。SEO メタデータは、Open Graph のタイトル、説明、画像などのメタタグ用 JSX を受け取る head プロパティで設定できます。useNextSeoProps 関数では、タイトルテンプレートを動的に設定できます。

---

高度なドキュメント

このスキルでは、段階的開示を使用します。詳しいパターンについては、modules ディレクトリを参照してください。

• modules/configuration.md には、theme.config の完全なリファレンスが記載されています
• modules/mdx-components.md では、MDX コンポーネントライブラリについて説明しています
• modules/i18n-setup.md には、国際化のガイドが記載されています
• modules/deployment.md では、ホスティングとデプロイについて説明しています

---

テーマのオプション

組み込みテーマには、ドキュメントサイトに推奨されるnextra-theme-docsと、ブログの実装向けのnextra-theme-blogがあります。

カスタマイズオプションには、色を設定するCSS変数、カスタムサイドバーコンポーネント、フッターのカスタマイズ、ナビゲーションレイアウトの変更があります。

---

デプロイ

人気のデプロイプラットフォームには、設定不要ですぐに使える推奨セットアップを備えたVercel、無料でセルフホストできるGitHub Pages、柔軟なCI/CD統合が可能なNetlify、そして完全に制御できるカスタムサーバーがあります。

Vercelにデプロイするには、npmを使用してVercel CLIをグローバルにインストールし、次にvercelコマンドを実行してプロジェクトを選択し、デプロイします。

---

他のスキルとの連携

補完的なスキルには、コードからドキュメントを自動生成するmoai-docs-generation、ドキュメントの品質を検証するmoai-workflow-docs、Markdownの書式を整えるmoai-cc-claude-mdがあります。

---

バージョン履歴

バージョン2.2.0は2026-01-11にリリースされました。CLAUDE.md Documentation Standardsに準拠するためコードブロックを削除し、すべての例を説明文に変更しました。

バージョン2.1.0は2025-12-30にリリースされました。Nextra固有のtheme.config.tsxパターンを完全に網羅するようconfiguration.mdを更新し、Nextra 4.x App Routerの設定パターンを追加し、Next.js 14および15とのバージョン互換性を更新し、Turbopackのサポートに関するドキュメントを追加しました。

バージョン2.0.0は2025-11-23にリリースされました。段階的開示を取り入れてリファクタリングし、設定パターンを強調表示して、MDX統合ガイドを追加しました。

バージョン1.0.0は2025-11-12にリリースされました。Nextraのアーキテクチャガイド、テーマ設定、i18nサポートを初めて提供しました。

---

メンテナンス担当：MoAI-ADK Team ドメイン：ドキュメントアーキテクチャ 生成元：MoAI-ADK Skill Factory

---

相性の良いツール

エージェント：

• workflow-docs：ドキュメント生成
• code-frontend：Nextraの実装
• workflow-spec：アーキテクチャドキュメント

スキル：

• moai-docs-generation：コンテンツ生成
• moai-workflow-docs：ドキュメントの検証
• moai-library-mermaid：図の統合

コマンド：

• moai:3-sync：ドキュメントのデプロイ
• moai:0-project：Nextraプロジェクトの初期化