rspress-description-generator

Rspress の説明文ジェネレーター

Rspress のフロントマターにある description フィールドは、検索エンジンのスニペット、ソーシャルメディアのプレビュー、llms.txt などの AI 向けフォーマットで使われる <meta name="description" content="..."> タグを生成します。

ステップ 1 — ドキュメントのルートを特定する

1. Rspress の設定ファイルを探します。rspress.config.ts、.js、.mjs、.cjs を検索します。プロジェクトのルート、または website/ のようなサブディレクトリ内にある場合があります。
2. 設定を読み込み、root オプションを確認します。
   • 値は単純な文字列（root: 'docs'）の場合も、JS の式（root: path.join(__dirname, 'docs')）の場合もあります。どちらの場合も、解決後のディレクトリパスを特定します。
   • root が設定されている場合は、設定ファイルのディレクトリを基準に解決します。
   • root が設定されていない場合は、設定ファイルのディレクトリを基準に docs を使用します。
3. ディレクトリが存在することを確認します。docs も設定されたルートも存在しない場合は、代わりに doc がないか確認します。

ステップ 2 — i18n の構成を検出する

Rspress の i18n プロジェクトでは、言語別のサブディレクトリ（例：en/、zh/）をドキュメントのルート直下に配置します。

docs/
├── en/
│   ├── guide/
│   └── index.md
└── zh/
    ├── guide/
    └── index.md

ドキュメントのルートに、言語別のサブディレクトリ（en、zh、ja、ko などの2文字のコード）があるか確認します。ある場合は、各言語のディレクトリを個別に処理します。説明文の言語は、コンテンツの言語と一致させてください。

言語別のサブディレクトリがない場合は、ドキュメントのルート全体を単一言語のサイトとして扱います。

ステップ 3 — ファイルをスキャンして処理する

ドキュメントのルート以下にある **/*.md と **/*.mdx を glob で検索します。次のものは除外します。

• node_modules、ビルド出力（doc_build、.rspress、dist）
• _meta.json / _nav.json（ドキュメントページではなく、サイドバー／ナビゲーションの設定ファイル）
• **/shared/** ディレクトリ（@import で取り込まれる再利用可能なスニペットで、単独のページではありません）

各ファイルについて、次の手順を実行します。

1. ファイルを読み込みます。
2. フロントマターに既存の description があるか確認します。 存在し、空でない場合はスキップします。
3. フロントマターの pageType を確認します。 home ページの場合は、本文ではなく hero.text / hero.tagline フィールドまたは機能一覧から説明文を作成します。
4. 以下の執筆ガイドラインに沿って説明文を作成します。
5. フロントマターに description を挿入します。

   • ファイルに title フィールドを含むフロントマターがある場合は、title の次の行に description を挿入します。

   • ファイルに title のないフロントマターがある場合は、最初のフィールドとして description を挿入します。

   • ファイルにフロントマターのブロックがない場合は、次のように追加します。

     ---
     description: Your generated description here
     ---
     

YAML の書式

説明文の多くは、引用符で囲まない YAML 文字列にできます。

description: Step-by-step guide to setting up your first Rspress site

説明文にコロン、引用符、その他の特殊な YAML 文字が含まれる場合は、二重引用符で囲みます。

description: 'API reference for Rspress configuration: plugins, themes, and build options'

ステップ 4 — 一括処理

ファイル数の多いサイトでは、並行するエージェント呼び出しを使用して、独立したファイルを同時に処理します。セクションごとの一貫性を保ち、作業に集中できるよう、ディレクトリごとにグループ分けします（例：まず guide/ 内のファイルすべて、次に api/ 内のファイルすべて）。

すべてのファイルを処理したら、簡単にスキャンして見落としがないか確認します。再度 glob で検索し、description のないファイルが残っていないか確認してください。

説明文の執筆ガイドライン

説明文は、検索エンジン（Google のスニペット）、AI システム（llms.txt、要約）、人間（検索結果の一覧）という3つの対象に向けたものです。優れた説明文は、そのすべてに役立ちます。

ルール

• 長さ：50～160文字。50文字未満では検索エンジンにとって情報が曖昧すぎ、160文字を超えるとスニペットで途中までしか表示されません。
• 言語：ドキュメントの内容に合わせます。中国語のドキュメントには中国語の説明文、英語のドキュメントには英語の説明文を付けます。
• 簡潔に書く：ページで扱う内容を述べます。「このドキュメントでは」「このページでは」「～について学びます」などの書き出しは避け、すぐに要点を述べてください。
• 具体的に書く：ページで扱う具体的なテクノロジー、API、概念に言及します。「検索、分析、国際化のための Rspress プラグインを設定する」は、「プラグインの使い方」よりも適切です。
• Markdown は使わない：書式構文を使わず、プレーンテキストのみを使用します。

例

良い例：

内容	説明
プラグイン開発ガイド	Node.js プラグイン API とランタイムフックを使って、カスタム Rspress プラグインを作成します
MDX コンポーネントの使用	MDX ドキュメントファイルで React コンポーネントをインポートして使用します
Rspress 快速开始	从安装到本地预览，搭建 Rspress 文档站点的完整流程
テーマ設定	Rspress テーマのナビゲーションバー、サイドバー、フッター、ダークモードをカスタマイズします
ホームページ（pageType: home）	Rspress ドキュメントフレームワーク — 高速で、MDX を活用した静的サイトジェネレーター

悪い例：

説明	理由
「プラグインについて」	曖昧すぎます — どのプラグインですか？何についてですか？
「このページでは Rspress テーマの設定方法を説明します」	「このページでは〜を説明します」に文字数を費やしています
「Rspress のすべてを学びましょう！」	宣伝文句にすぎず、具体的な内容がありません

ドキュメント

• Frontmatter フィールド：https://rspress.rs/api/config/config-frontmatter
• 基本設定（root オプション）：https://rspress.rs/api/config/config-basic
• Rspress の全ドキュメント：https://rspress.rs/llms.txt