Component reference pages reordered and cleaned up

Web Awesome のコンポーネントリファレンスページを、概要 → API → 例の順に並び替え、さらにエージェント向けの余計なフッターを除去しました。この変更により、エージェントが API 情報に直接アクセスでき、長いサンプル例を解析するトークンコストが削減されます。

背景

従来のコンポーネントページは概要の後に例が続き、最後に API が記載されていました。 エージェントは例をスキャンしてから API 部分にたどり着く必要があり、不要なトークンを大量に消費していました。今回の PR は、エージェントが最も必要とする API 情報を先に提示することで、トークン使用量と応答遅延を削減することを目的としています。

Web Awesome のエージェントスキルは、Markdown 形式でコンポーネント情報を提供します。 その生成プロセスは Eleventy の HTML 出力をパースし、processHtmlToMarkdown 関数でクリーンな Markdown に変換しています。変更前はレイアウトテンプレートが例を先に出力していたため、スキル側で順序を入れ替える必要がありました。

この背景から、生成段階で順序を調整し、不要なヘルプフッターを削除する方針が採られました。 後方互換性を保ちつつ、エージェント向けドキュメントの構造を最適化する設計判断です。

技術的な変更

moveExamplesToEnd 関数を追加し、## Examples セクションを末尾へ移動します。 正規表現 /\n## Examples\n[\s\S]*?(?=\n## |$)/ で例ブロック全体を抽出し、元の位置から除去した上で Markdown の末尾に再付与しています。

function moveExamplesToEnd(markdown) {
  const match = markdown.match(/\n## Examples\n[\s\S]*?(?=\n## |$)/);
  if (!match) return markdown;
  const examples = match[0];
  return (markdown.slice(0, match.index) + markdown.slice(match.index + examples.length)).trimEnd() + '\n' + examples;
}

processHtmlToMarkdown に例順序の調整ロジックとフッター除去ロジックを統合しました。 component-help 要素とその直前の WA-DIVIDER を削除し、moveExamplesToEnd をコンポーネントドキュメント向けに呼び出しています。

// Remove the "Need a hand?" help footer and its leading divider
main.querySelectorAll('.component-help').forEach(el => {
  const divider = el.previousElementSibling;
  if (divider && divider.tagName === 'WA-DIVIDER') divider.remove();
  el.remove();
});
...
if (component) {
  markdown = moveExamplesToEnd(markdown);
}

CHANGELOG には「Reordered component reference pages in the webawesome Agent Skill to put the import instructions and API tables before the examples」と追記され、ドキュメントリファクタリングが公式に記録されています。

設計判断

レイアウトテンプレートを変更せず、生成後の Markdown を加工するアプローチが採用されました。 既存の _layouts/component.njk は多数の利用箇所で共有されているため、テンプレート自体の変更はリグレッションリスクが高くなります。そこで、HTML → Markdown の変換段階で順序入れ替えを行うことで、影響範囲をスクリプトに限定しています。

moveExamplesToEnd は単一の正規表現マッチに依存し、シンプルかつ高速に動作します。 例セクションは連続した ## 見出しブロックとして扱える前提で実装され、他の見出し構造に影響を与えません。これにより、既存のコンポーネントドキュメントの整合性を保ちつつ、エージェント向けの最適化が実現されています。

フッタ除去はエージェントスキルが不要と判断した UI 要素のみを対象にしています。 component-help とその前の WA-DIVIDER を削除することで、ドキュメントサイズが削減され、トークン使用量がさらに減少します。この選択は、エージェント利用シナリオに特化した最小限の情報提供という設計方針と一致します。

まとめ

この PR は、Web Awesome のコンポーネントリファレンスをエージェントが利用しやすい構造へと再編成し、不要なフッターを除去することでトークンコストを削減しました。生成ロジックだけを変更する安全なアプローチにより、既存のテンプレートやドキュメントの互換性を保ちつつ、エージェントスキルの効率性が向上しています。