From 8ad7a81181826d8523dd55b233f3fd2d2ac97023 Mon Sep 17 00:00:00 2001 From: Kenzo-Wada Date: Sat, 11 Oct 2025 15:54:50 +0900 Subject: [PATCH 1/3] i18n(ja): added translation for `route-data` --- .../src/content/docs/ja/guides/route-data.mdx | 139 ++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/src/content/docs/ja/guides/route-data.mdx diff --git a/docs/src/content/docs/ja/guides/route-data.mdx b/docs/src/content/docs/ja/guides/route-data.mdx new file mode 100644 index 00000000000..95d4392c77d --- /dev/null +++ b/docs/src/content/docs/ja/guides/route-data.mdx @@ -0,0 +1,139 @@ +--- +title: ルートデータ +description: Starlight のページデータモデルがどのようにページをレンダリングするか、またそのカスタマイズ方法について学びましょう。 +--- + +import { Steps } from '@astrojs/starlight/components'; + +Starlight がドキュメント内のページをレンダリングするとき、まずそのページ上の内容を表すルートデータオブジェクトを作成します。 +このガイドでは、ルートデータがどのように生成され、どのように使用されるか、また Starlight の既定の動作を変更するためにカスタマイズする方法を説明します。 + +利用可能なすべてのプロパティ一覧については、[「ルートデータリファレンス」](/ja/reference/route-data/) を参照してください。 + +## ルートデータとは？ + +Starlight のルートデータは、1 ページをレンダリングするために必要なすべての情報を含むオブジェクトです。 +これは、現在のページに関する情報に加え、Starlight の設定から生成されるデータも含みます。 + +## ルートデータの使用方法 + +Starlight のすべてのコンポーネントは、ルートデータを使用して各ページで何をレンダリングするかを決定します。 +たとえば、[`siteTitle`](/ja/reference/route-data/#sitetitle) 文字列はサイトタイトルの表示に使用され、[`sidebar`](/ja/reference/route-data/#sidebar) 配列はグローバルサイドバーのナビゲーションをレンダリングするために使用されます。 + +このデータは Astro コンポーネント内で `Astro.locals.starlightRoute` グローバルからアクセスできます。 + +```astro title="example.astro" {2} +--- +const { siteTitle } = Astro.locals.starlightRoute; +--- + +

このサイトのタイトルは「{siteTitle}」です。

+``` + +これは、表示内容をカスタマイズするために [コンポーネントのオーバーライド](/ja/guides/overriding-components/) を作成するときなどに便利です。 + +## ルートデータのカスタマイズ + +Starlight のルートデータは、設定なしでそのまま動作します。 +しかし、高度なユースケースでは、サイトの表示方法を変更するために一部またはすべてのページでルートデータをカスタマイズしたい場合があります。 + +これは [コンポーネントのオーバーライド](/ja/guides/overriding-components/) と似た概念ですが、Starlight がデータを「どのように」レンダリングするかを変更する代わりに、Starlight が「レンダリングするデータ自体」を変更します。 + +### ルートデータをカスタマイズすべき場合 + +既存の設定オプションでは実現できない形で、Starlight がデータを処理する方法を変更したい場合にルートデータのカスタマイズが役立ちます。 + +たとえば、サイドバー項目をフィルタリングしたり、特定のページのタイトルをカスタマイズしたりできます。 +このような変更は、Starlight の既定コンポーネントを変更することなく、これらのコンポーネントに渡すデータを修正するだけで実現できます。 + +### ルートデータをカスタマイズする方法 + +ルートデータは特別な形式の「ミドルウェア」を使ってカスタマイズできます。 +これは Starlight がページをレンダリングするたびに呼び出され、ルートデータオブジェクト内の値を変更できる関数です。 + + + +1. Starlight の `defineRouteMiddleware()` ユーティリティを使って、`onRequest` 関数をエクスポートする新しいファイルを作成します。 + + ```ts + // src/routeData.ts + import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; + + export const onRequest = defineRouteMiddleware(() => {}); + ``` + +2. `astro.config.mjs` で、ルートデータミドルウェアファイルの場所を Starlight に指定します。 + + ```js ins={9} + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'My delightful docs site', + routeMiddleware: './src/routeData.ts', + }), + ], + }); + ``` + +3. `onRequest` 関数を更新してルートデータを変更します。 + + ミドルウェアが最初に受け取る引数は [Astro の `context` オブジェクト](https://docs.astro.build/en/reference/api-reference/) です。 + これには、現在のページレンダリングに関するすべての情報（現在の URL や `locals` など）が含まれています。 + + 次の例では、すべてのページタイトルの末尾に感嘆符を追加して、ドキュメントを少し楽しくします。 + + ```ts + // src/routeData.ts + import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; + + export const onRequest = defineRouteMiddleware((context) => { + // このページのコンテンツコレクションエントリを取得 + const { entry } = context.locals.starlightRoute; + // タイトルの末尾に感嘆符を追加 + entry.data.title = entry.data.title + '!'; + }); + ``` + + + +#### 複数のルートミドルウェア + +Starlight は複数のミドルウェアもサポートしています。 +複数のハンドラーを追加する場合は、`routeMiddleware` にパスの配列を設定します。 + +```js {9} +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'My site with multiple middleware', + routeMiddleware: ['./src/middleware-one.ts', './src/middleware-two.ts'], + }), + ], +}); +``` + +#### 後続のルートミドルウェアを待機する + +スタック内の後続ミドルウェアが実行されるのを待ってからコードを実行したい場合、ミドルウェア関数の第 2 引数として渡される `next()` コールバックを `await` することができます。 +これは、たとえばプラグインのミドルウェアが実行された後に変更を加えたい場合に便利です。 + +```ts "next" "await next();" +// src/routeData.ts +import { defineRouteMiddleware } from '@astrojs/starlight/route-data'; + +export const onRequest = defineRouteMiddleware(async (context, next) => { + // 後続のミドルウェアが実行されるのを待つ + await next(); + // ルートデータを変更 + const { entry } = context.locals.starlightRoute; + entry.data.title = entry.data.title + '!'; +}); +``` From b05eacc233acfd12a9454dabfe152e88f4c86db2 Mon Sep 17 00:00:00 2001 From: Kenzo-Wada Date: Sat, 18 Oct 2025 21:12:50 +0900 Subject: [PATCH 2/3] chore: link japanese page --- docs/src/content/docs/ja/guides/route-data.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/ja/guides/route-data.mdx b/docs/src/content/docs/ja/guides/route-data.mdx index 95d4392c77d..788f64aa6ad 100644 --- a/docs/src/content/docs/ja/guides/route-data.mdx +++ b/docs/src/content/docs/ja/guides/route-data.mdx @@ -81,7 +81,7 @@ Starlight のルートデータは、設定なしでそのまま動作します 3. `onRequest` 関数を更新してルートデータを変更します。 - ミドルウェアが最初に受け取る引数は [Astro の `context` オブジェクト](https://docs.astro.build/en/reference/api-reference/) です。 + ミドルウェアが最初に受け取る引数は [Astro の `context` オブジェクト](https://docs.astro.build/ja/reference/api-reference/) です。 これには、現在のページレンダリングに関するすべての情報（現在の URL や `locals` など）が含まれています。 次の例では、すべてのページタイトルの末尾に感嘆符を追加して、ドキュメントを少し楽しくします。 From ba1f7e509a3241826665a3f09e695edb02cf3cd2 Mon Sep 17 00:00:00 2001 From: Kenzo-Wada Date: Sat, 18 Oct 2025 21:14:00 +0900 Subject: [PATCH 3/3] chore: added missing translations --- docs/src/content/docs/ja/guides/route-data.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/ja/guides/route-data.mdx b/docs/src/content/docs/ja/guides/route-data.mdx index 788f64aa6ad..c653db7976a 100644 --- a/docs/src/content/docs/ja/guides/route-data.mdx +++ b/docs/src/content/docs/ja/guides/route-data.mdx @@ -72,7 +72,7 @@ Starlight のルートデータは、設定なしでそのまま動作します export default defineConfig({ integrations: [ starlight({ - title: 'My delightful docs site', + title: 'カスタムルートデータのページ', routeMiddleware: './src/routeData.ts', }), ], @@ -113,7 +113,7 @@ import starlight from '@astrojs/starlight'; export default defineConfig({ integrations: [ starlight({ - title: 'My site with multiple middleware', + title: '複数のミドルウェアのページ', routeMiddleware: ['./src/middleware-one.ts', './src/middleware-two.ts'], }), ],