rspress-best-practices

Rspress のベストプラクティス

Rspress（v2）のサイトを作成またはレビューする際は、以下のルールに従ってください。

設定

• @rspress/core の defineConfig を使い、rspress.config.ts を設定します
• ドキュメントがデフォルトの docs/ ディレクトリにない場合は、root を明示的に設定します
• title、description、icon、logo、base、lang などのサイト全体の設定は、ページファイルで繰り返さず、設定ファイルに記述します
• カスタムテーマコードや低レベルのバンドラー設定を上書きする前に、Rspress の標準オプションを優先します
• カスタムテーマコードはトップレベルの theme/ ディレクトリに置き、@rspress/core/theme-original から元のテーマの要素をインポートします

CLI

• ローカル開発には rspress dev を使います
• 本番用の出力には rspress build を使います
• ビルド済みサイトのローカルプレビューにのみ rspress preview を使います
• CSS 変数、クラスの上書き、レイアウトのラッピングではカスタマイズを実現できない場合にのみ、rspress eject を使います

ドキュメントの構成とナビゲーション

• ドキュメントのコンテンツは明確な1つのドキュメントルートの下にまとめ、チームの担当範囲ではなく、トピックやワークフローごとにページを分類します
• ファイル名で順序を表現するのではなく、_meta.json または _nav.json を使ってサイドバーやナビゲーションのラベルと順序を制御します
• 再利用可能な MDX スニペットや共有コンポーネントは、ページ間で重複させず、共有ファイルに配置します
• ランディングページは簡潔にし、そこからタスク別の詳細ガイドにリンクします

執筆とフロントマター

• 明確な title と description のフロントマターを追加し、ページのデフォルト設定では不十分な場合にのみ sidebar、outline、navbar、footer を設定します
• レイアウトのニーズに応じて、pageType: home、doc、doc-wide、custom、blank を適切に使います
• タスクを中心とした見出しと短い導入文を使い、技術ドキュメントでは宣伝色の強い文章を避けます
• 1ページにつき1つのトピックを扱い、長すぎるページはワークフローや機能領域ごとに分割します
• コード例は最小限にし、実行可能で、対象バージョンに正確なものにします

MDX とコンポーネント

• インタラクティブなドキュメントや埋め込みコンポーネントには MDX を使いますが、本文の内容は通常の Markdown としても理解できるようにします
• 内部ソースパスからインポートするのではなく、ドキュメント化された Rspress のテーマ／ランタイム API を優先します
• アプリ全体の UI やプロバイダーには、各ページでインポートを繰り返すのではなく、globalUIComponents またはテーマの上書きを使います

テーマとスタイル

• ブランドカラー、間隔、サーフェスのスタイルには CSS 変数を優先します
• 組み込みコンポーネントを切り離す前に、BEM クラスの上書きや Layout スロットを優先します
• theme/ 内のファイルでは、名前付きエクスポートを意図的に置き換える場合を除き、export * from '@rspress/core/theme-original' を維持します
• 設定、CSS、ラッピングでは要件を満たせない場合を除き、コンポーネント全体の切り離しは避けます

I18n、検索、AI

• 多言語サイトでは、言語ごとのディレクトリにロケール別のコンテンツを配置し、可能な範囲でナビゲーションの構成を揃えます
• 説明文などのフロントマターテキストは、ページ本文と同じ言語にします
• 検索は意図を持って設定します。小規模または中規模のサイトにはローカル検索を使い、規模の拡大やバージョンをまたいだインデックス作成が必要な場合はホスト型検索を使います
• llms または ssgMd は、機械可読な出力がサイトに役立つ場合にのみ有効にし、これらの出力にはページの概要が表示されるため、説明文を正確に保ちます

アセットと公開ファイル

• コンテンツに属する画像やコンポーネントは、docs／theme のソースからインポートします
• public/ は、ファビコン、ソーシャル画像、ダウンロードファイルなど、URL パスを固定する必要があるアセットにのみ使います
• 公開アセットはサイト内の絶対パスで参照し、base が設定されていても機能することを確認します

プラグインと統合

• カスタムソリューションを構築する前に、検索、プレビュー、API ドキュメントの用途では公式の Rspress プラグインを優先します
• コンポーネントやライブラリのドキュメントでインタラクティブなデモや API テーブルが必要な場合は、@rspress/plugin-preview と @rspress/plugin-api-docgen を使います
• プラグインの使用状況は設定で明示し、保守コストを抑えるため未使用のプラグインは削除します

ビルド、デプロイ、デバッグ

• rspress dev と rspress build の両方で検証してください。開発環境で動作するページでも、静的生成時に失敗することがあります。
• デプロイ前に、リンク切れ、アセットの不足、base の誤った処理がないか確認してください。
• ホスティングのワークフローで生成物のコミットが明示的に必要な場合を除き、生成された出力はソース管理の対象外にしてください。
• コンテンツの問題をデバッグする場合は、バンドラーの問題だと決めつける前に、解決済みのドキュメントルート、フロントマター、テーマのオーバーライドを確認してください。

ドキュメント

• 最新の Rspress ドキュメントについては、https://rspress.rs/llms.txt を参照してください。
• オプション名の正確な表記や現在の動作を確認する際は、設定および API のドキュメントを参照してください。