プラグインとスクリプト
サイトは Docsy のスクリプトに加えて assets/js/ 配下にいくつか独自のスクリプトを追加しており、3 つの方法で読み込まれます。
- プラグイン、Docsy のローダー経由
- フックスクリプト、body-end フック（一覧）および head-end フック（1 つのスクリプト、Kapa ウィジェットの事前初期化）経由
- ショートコードスクリプト、それを必要とする機能のショートコードによる読み込み（例: レジストリ検索フォーム、config-types アコーディオン）
フックとショートコードは script.html パーシャルを通じてスクリプトを読み込みます。
Hugo の js.Build が各ファイルをバンドルし、本番ビルドではさらにミニファイ、フィンガープリント付与、サブリソース整合性の追加も行います。
プラグイン
サイトプラグインは otel- 接頭辞のもと、Docsy の custom-script contract に従います。
独自のマークアップをレンダリングするプラグインは、そのマークアップを所有し、ページにマークを付けるショートコードによってゲートされるため、ゲートはコンテンツとともにそれを配信するすべての言語に引き継がれます。
shim はそのマークを読み取ります。
インクルードされたコンテンツ内のショートコードは、インクルード元のページではなく、インクルードされたページにマークを付けます（Page flags in included content）。
ベンチマークプラグイン
benchmarks ショートコードは、リポジトリのベンチマーク履歴、つまり github-action-benchmark が GitHub Pages 上に公開する data.js（その形状はアクションの source types）をチャートにします。
ショートコードはデータを指定し、3 つのオプション引数でその読み取り方を指示します。
data_url のみの場合、各ベンチマークはデータが存在するコミット上に描画される独立したチャートになります（コミット内でベンチマーク名が一意であることが前提）。
{{< benchmarks data_url="param:otel-benchmarks.data_url" >}}
group_separator を指定すると、各チャートは複数のベンチマークをシリーズとして保持します。
Collector benchmarks ページがデータを読み取る方法がこれです。
{{< benchmarks data_url="param:otel-benchmarks.data_url" filter="10kDPS,10kSPS" group_separator="/" series_separator=" - " >}}
group_separator がある場合、チャートはデータセットのコミット軸を共有するためシリーズが揃い、凡例とツールチップにシリーズ名が表示されます。
ない場合、各チャートにはどちらも表示されず、タイトルがその 1 つのシリーズの名前になります。
data_url: アクションのdata.js。https://…の形式か、param:NAMEの形式（それを保持するページパラメーター）で指定します。 ページのプローズが_paramを通じて同じ URL をリンクできるようにするためです。filter（オプション）:extraにカンマ区切りの文字列のいずれかを含むベンチマークを保持します。group_separator（オプション）:extraをグループ（ベンチマーク名と結合されてチャートのタイトルになる）とシリーズ名に分割します。 セパレーターを含まないextraはグループとシリーズの両方になります。series_separator（オプション）: シリーズ名を最初の出現位置でトリミングします。group_separatorがなければシリーズ名は存在せず、この引数は何もしません。
引数の動作はバリデーションを含めてショートコードの doc コメントに記載されています。 リンクやテキストはページのプローズに属し、各言語が独自に記述します。 データリンクは、ショートコードの Markdown 出力が空であるため、エージェントが数値にアクセスするためのパスでもあります。
ショートコードの背後にある otel-benchmarks プラグインは、アクションの stock renderer のフォークです。
その構成要素は以下のとおりです。
- ショートコード、
layouts/_shortcodes/benchmarks.html: チャートコンテナを出力し、shim とコンパニオン用にデータ URL を記録します。 各呼び出しはその場所にチャートセットをレンダリングします。 - Markdown バリアント、同じ場所にある
benchmarks.md: 空であるため、チャートのマークアップはページの Markdown output に含まれません（Agent support）。 - Shim、
layouts/_partials/scripts/plugins/otel-benchmarks_docsy-shim.html（Adjust a plugin per page）: ショートコードのないページでプラグインを無効にし、リモートデータスクリプトをそれ以外のすべてのページから排除します（Security）。 - コンパニオン、
layouts/_partials/scripts/plugins/otel-benchmarks.html（Plugin files）: エントリのversionピンで Chart.js をベンダリングし、データファイルを読み込みます。 データはライブのリモートスクリプトのまま残されるため、チャートはサイトビルド間でも更新されます。 固定の整合性ハッシュではこれが禁止されます。 - スクリプト、
assets/js/plugins/otel-benchmarks/（Plugin files）: レンダラーindex.jsと、凡例、ツールチップとポップオーバーにポイントが表示する内容、およびポップオーバー自体のヘルパーです。 - スタイルシート、
assets/scss/plugins/otel-benchmarks.scss（Plugin files）: チャートのレイアウトで、コンテナにスコープされています。 インラインコピーは stock ページのstatic/css/benchmarks.cssを保持しており、そのむき出しのmain、button、footerセレクターは Docsy のクロームにも到達します。 - 登録、
config/_default/hugo.yaml（Configuration reference）: shim がページごとに判断するため、サイトレベルのエントリが 1 つです。 - テスト、
tests/public/otel-benchmarks.test.mjs: 各ページのビルド済みコピーの配信を検証します。 そのPAGESテーブルはプラグインを使用するページと、まだインラインのローカライズ済みコピーの一覧であり、それらの変換は #12266 で追跡されています。
Body-end スクリプト
| スクリプト | ページ | 目的 |
|---|---|---|
blog-sidebar-entry-opener.js | ブログインデックスとページャーページ（最初のページに作用） | サイドバーの最新 2 つの年グループを開く |
imageZoom.js | すべて | コンテンツ画像のクリック拡大 |
navScroll.js | すべて | サイドバーのアクティブエントリをビューにスクロールすることを意図していますが、アクティブ状態がこのスクリプトの実行後に適用されるため、現在は動作しません |
tracing.js | Netlify ビルド、一時停止解除時 | Website telemetry、一時停止中 |
ブログサイドバーエントリオープナー
blog-sidebar-entry-opener.js は、ページにゲートされた唯一の body-end スクリプトであり、サイドバーに作用する唯一のスクリプトです。
ブログインデックスへのゲート
body-end フックはすべてのページでレンダリングされるため、オープナーはページの .Path でゲートされます。
.Path はすべてのロケールで同一です: {{ if eq .Path "/blog" }}。
.Path ゲートでは、ページネーションされたリストの最初のページだけを特定できません。
Hugo はリストのページャーページを 1 つのセクションページからレンダリングするため、.Path、.RelPermalink、.Pages は /blog/ と /blog/page/2/ で同一であり、現在のスライスはページャー（.Paginator、または .Paginate が返したもの）だけが認識できます。
Docsy のテンプレートがページネーションしないままにしているリストページ（空のブログなど）で .Paginator を呼び出すと、そのページがページネーションされ、page/1/ エイリアスが公開されます。
そのため、オープナーはすべてのページャーページで読み込まれ、実行時に location.pathname で /page/ を検査してスキップします。
サイドバーへの作用
サイトは Docsy のキャッシュ済みサイドバー（ui.sidebar_cache_limit: 1）を使用します。
これはサイドバールートごとに 1 つのナビゲーションで、アクティブ状態なしの非表示（d-none）で配信されます。
Docsy の chrome-nav.js は DOMContentLoaded 時にこれをハイドレートします。
アクティブ状態を適用してナビゲーションを表示します。
ブログインデックスは、すべてのセクションのランディングページと同様に、両方のビルド種類でそのナビゲーションをインラインで保持するため、body-end スクリプトはパース中、表示前に実行され、サイドバーが表示される前にサイドバーの状態を設定できます。
オープナーはそのとき 2 つの年グループをチェックします。
リーンビルドでは、他のページはプレースホルダーを保持し、chrome-nav.js がナビゲーションをフェッチ後に埋めますが、body-end スクリプトには遅すぎます。
JavaScript が無効の場合、サイドバーは非表示のままです。