設定方法

`starlight`インテグレーションの設定

StarlightはAstroウェブフレームワークの上に構築されたインテグレーションです。astro.config.mjs設定ファイル内でプロジェクトの設定をおこないます。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: '私の楽しいドキュメントサイト',
    }),
  ],
});

以下のオプションをstarlightインテグレーションに設定できます。

`title`（必須）

type: string | Record<string, string>

ウェブサイトのタイトルを設定します。メタデータとブラウザのタブのタイトルに使用されます。

文字列を設定できますが、多言語サイトの場合は、異なるロケールごとの値をもつオブジェクトも使用できます。オブジェクト形式を使用する場合、キーはBCP-47タグ（en、ar、zh-CNなど）である必要があります。

starlight({
  title: {
    en: 'My delightful docs site',
    de: 'Meine bezaubernde Dokumentationsseite',
  },
});

`description`

type: string

ウェブサイトの説明を設定します。descriptionがページのフロントマターに設定されていない場合、<meta name="description">タグで検索エンジンに共有するメタデータとして使用されます。

`logo`

type: LogoConfig

ナビゲーションバーにサイトタイトルと並べて、またはその代わりとして表示するロゴ画像を設定します。単一のsrcプロパティを設定するか、lightとdark用に別々の画像ソースを設定できます。

starlight({
  logo: {
    src: './src/assets/my-logo.svg',
  },
});

`LogoConfig`

type LogoConfig = { alt?: string; replacesTitle?: boolean } & (
  | { src: string }
  | { light: string; dark: string }
);

`tableOfContents`

type: false | { minHeadingLevel?: number; maxHeadingLevel?: number }
default: { minHeadingLevel: 2, maxHeadingLevel: 3 }

各ページの右側に表示される目次を設定します。デフォルトでは、<h2>と<h3>の見出しがこの目次に含まれます。

`editLink`

type: { baseUrl: string }

editLink.baseUrlを設定すると、「ページを編集」リンクが有効になります。最終的なリンクは、editLink.baseUrl + 現在のページのパスになります。たとえば、GitHubのwithastro/starlightリポジトリのページを編集するには以下のようにします。

starlight({
  editLink: {
    baseUrl: 'https://github.com/withastro/starlight/edit/main/',
  },
});

この設定により、/introductionページにはhttps://github.com/withastro/starlight/edit/main/src/content/docs/introduction.mdを指す編集リンクが表示されます。

`sidebar`

type: SidebarItem[]

サイトのサイドバーのナビゲーション項目を設定します。

サイドバーはリンクとリンクのグループの配列です。slugを使用する場合を除き、各項目はlabelと以下のプロパティのいずれかが必要です。

link — 特定のURL、たとえば'/home'や'https://example.com'などへの単一のリンク。
slug — たとえば'guides/getting-started'など、内部ページへの参照。
items — サイドバーの複数のリンクとサブグループを含む配列。
autogenerate — リンクのグループを自動的に生成するために、ドキュメントのディレクトリを指定するオブジェクト。

内部リンクは、slugプロパティをもつオブジェクトの代わりに文字列として指定することもできます。

starlight({
  sidebar: [
    // 「ホーム」というラベルのついた単一のリンク。
    { label: 'ホーム', link: '/' },
    // 4つのリンクを含む、「ここから始める」というラベルのついたグループ。
    {
      label: 'ここから始める',
      items: [
        // 内部リンクに`slug`を使用する。
        { slug: 'intro' },
        { slug: 'installation' },
        // 内部リンクのための省略形を使用する。
        'tutorial',
        'next-steps',
      ],
    },
    // referenceディレクトリのすべてのページにリンクするグループ。
    {
      label: 'リファレンス',
      autogenerate: { directory: 'reference' },
    },
  ],
});

並び順

自動生成されたサイドバーグループは、ファイル名のアルファベット順に並べ替えられます。たとえば、astro.mdから生成されたページは、starlight.mdというページの上に表示されます。

グループの折りたたみ

リンクのグループはデフォルトで展開されます。collapsedプロパティをtrueに設定して、この動作を変更できます。

自動生成されたサブグループは、デフォルトでは親グループのcollapsedプロパティに従います。autogenerate.collapsedプロパティを設定して、これを上書きできます。

sidebar: [
  // 折りたたまれたリンクのグループ。
  {
    label: '折りたたまれたリンク',
    collapsed: true,
    items: ['intro', 'next-steps'],
  },
  // 自動生成される折りたたまれたサブグループを含む展開されたグループ。
  {
    label: '参照',
    autogenerate: {
      directory: 'reference',
      collapsed: true,
    },
  },
],

ラベルの翻訳

多言語対応が必要なサイトの場合、各項目のlabelはデフォルトのロケールのものとみなされます。サポート対象の言語のラベルを提供するには、translationsプロパティを設定します。

sidebar: [
  // ブラジルポルトガル語に翻訳されたラベルをもつサイドバーの例。
  {
    label: 'ここから始める',
    translations: { 'pt-BR': 'Comece Aqui' },
    items: [
      {
        label: '開始する',
        translations: { 'pt-BR': 'Introdução' },
        link: '/getting-started',
      },
      {
        label: 'プロジェクトの構造',
        translations: { 'pt-BR': 'Estrutura de Projetos' },
        link: '/structure',
      },
    ],
  },
],

`SidebarItem`

type SidebarItem =
  | string
  | ({
      translations?: Record<string, string>;
      badge?: string | BadgeConfig;
    } & (
      | {
          // リンク
          link: string;
          label: string;
          attrs?: Record<string, string | number | boolean | undefined>;
        }
      | {
          // 内部リンク
          slug: string;
          label?: string;
          attrs?: Record<string, string | number | boolean | undefined>;
        }
      | {
          // リンクのグループ
          label: string;
          items: SidebarItem[];
          collapsed?: boolean;
        }
      | {
          // 自動生成されたリンクのグループ
          label: string;
          autogenerate: {
            directory: string;
            collapsed?: boolean;
            attrs?: Record<string, string | number | boolean | undefined>;
          };
          collapsed?: boolean;
        }
    ));

`BadgeConfig`

interface BadgeConfig {
  text: string;
  variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
  class?: string;
}

`locales`

type: { [dir: string]: LocaleConfig }

サイトの国際化（i18n）をおこなうには、サポート対象のlocalesを設定します。

各エントリは、その言語のファイルが保存されているディレクトリ名をキーとして使用する必要があります。

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Site',
      // このサイトのデフォルト言語を英語に設定します。
      defaultLocale: 'en',
      locales: {
        // 英語のドキュメントは`src/content/docs/en/`にあります。
        en: {
          label: 'English',
        },
        // 簡体字中国語のドキュメントは`src/content/docs/zh-cn/`にあります。
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // アラビア語のドキュメントは`src/content/docs/ar/`にあります。
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
      },
    }),
  ],
});

`LocaleConfig`

interface LocaleConfig {
  label: string;
  lang?: string;
  dir?: 'ltr' | 'rtl';
}

各ロケールに対し以下のオプションを設定できます。

`label`（必須）

type: string

たとえば言語の切替機能などでユーザーに表示する、この言語を表わすラベルです。ほとんどの場合、このラベルは、その言語を使用するユーザーが読みたいと思う言語の名前にすることが望ましいでしょう。たとえば、"English"、"العربية"、"简体中文"などです。

`lang`

type: string

この言語のBCP-47タグです。たとえば"en"、"ar"、"zh-CN"などです。設定されていない場合、デフォルトでは言語のディレクトリ名が使用されます。"pt-BR"や"en-US"のように地域タグが含まれる言語タグは、その地域専用の翻訳が見つからない場合、ベース言語の組み込みUI翻訳が使用されます。

`dir`

type: 'ltr' | 'rtl'

この言語を記述する方向です。左から右へ（デフォルト）は"ltr"を、右から左へは"rtl"を設定します。

ルートロケール

rootロケールを設定することで、/lang/ディレクトリなしでデフォルト言語を提供できます。

starlight({
  locales: {
    root: {
      label: 'English',
      lang: 'en',
    },
    fr: {
      label: 'Français',
    },
  },
});

この設定により、たとえば/getting-started/を英語のルートとし、対応するフランス語のページを/fr/getting-started/として提供することができます。

`defaultLocale`

type: string

このサイトのデフォルト言語を設定します。この値は、localesオブジェクトのキーのいずれかと一致する必要があります。（デフォルト言語がルートロケールの場合は、この設定をスキップできます。）

翻訳がない場合には、デフォルトロケールがフォールバックコンテンツとして使用されます。

`social`

type: Array<{ label: string; icon: StarlightIcon; href: string }>

このサイトのソーシャルメディアアカウントに関する任意の項目です。各エントリは、サイトヘッダーにアイコンリンクとして表示されます。

starlight({
  social: [
    { icon: 'codeberg', label: 'Codeberg', href: 'https://codeberg.org/knut' },
    { icon: 'discord', label: 'Discord', href: 'https://astro.build/chat' },
    { icon: 'github', label: 'GitHub', href: 'https://github.com/withastro' },
    { icon: 'gitlab', label: 'GitLab', href: 'https://gitlab.com/delucis' },
    { icon: 'mastodon', label: 'Mastodon', href: 'https://m.webtoo.ls/@astro' },
  ],
}),

`customCss`

type: string[]

Starlightサイトの見た目をカスタマイズするためのCSSファイルを設定します。

プロジェクトのルートからの相対パスで指定したローカルのCSSファイル（'./src/custom.css'など）と、npmモジュールとしてインストールしたCSS（'@fontsource/roboto'など）に対応しています。

starlight({
  customCss: ['./src/custom-styles.css', '@fontsource/roboto'],
});

`markdown`

type: { headingLinks?: boolean; processedDirs?: string[] }
default: { headingLinks: true, processedDirs: [] }

StarlightのMarkdown処理を設定します。

`headingLinks`

type: boolean
default: true

見出しにクリック可能なアンカーリンクを付けてレンダリングするかどうかを制御します。

starlight({
  markdown: {
    // Starlightのクリック可能な見出しアンカーリンクを無効にする。
    headingLinks: false,
  },
}),

`processedDirs`

type: string[]
default: []

StarlightのMarkdownパイプラインで処理される追加のディレクトリを定義します。デフォルトでは、StarlightのdocsLoader()を使用して読み込まれたMarkdownおよびMDXコンテンツのみが処理されます。プロジェクトのルートからの相対パスでローカルディレクトリを指定できます（例: './src/data/comments/'）。

Starlightの処理には、クリック可能な見出しアンカーリンク、補足情報のMarkdownディレクティブ構文、およびコードブロックのRTLサポートが含まれます。このオプションは、カスタムページで<StarlightPage>コンポーネントを使用してカスタムコンテンツコレクションのコンテンツをレンダリングしており、そのコンテンツにもStarlightのMarkdown処理を適用したい場合に便利です。

starlight({
  markdown: {
    // `src/data/reviews/`ディレクトリにある`reviews`コンテンツコレクションの
    // Markdownファイルを処理する。
    processedDirs: ['./src/data/reviews/'],
  },
}),

`expressiveCode`

type: StarlightExpressiveCodeOptions | boolean
default: true

Starlightは、Expressive Codeを使用して、コードブロックのレンダリングやコード例の一部のハイライト、コードブロックへのファイル名の追加などをおこなっています。MarkdownやMDXのコンテンツでExpressive Code構文を使用する方法については、「コードブロック」ガイドを参照してください。

Expressive Code標準の設定オプションはすべて使用できます。また、StarlightのexpressiveCodeオプションを設定することで、Starlight固有のプロパティも使用できます。たとえば、Expressive CodeのstyleOverridesオプションを設定して、デフォルトのCSSを上書きできます。これにより、コードブロックに角丸を付けるなどのカスタマイズが可能になります。

starlight({
  expressiveCode: {
    styleOverrides: { borderRadius: '0.5rem' },
  },
});

Expressive Codeを無効にするには、Starlightの設定でexpressiveCode: falseを設定します。

starlight({
  expressiveCode: false,
});

標準のExpressive Codeオプションに加えて、expressiveCodeの設定に以下のStarlight固有のプロパティを追加することで、コードブロックのテーマの動作をさらにカスタマイズできます。

`themes`

type: Array<string | ThemeObject | ExpressiveCodeTheme>
default: ['starlight-dark', 'starlight-light']

コードブロックのスタイルに使用するテーマを設定します。サポートされているテーマのフォーマットの詳細については、Expressive Codeのthemesドキュメントを参照してください。

Starlightは、デフォルトでSarah DrasnerのNight Owlテーマのダークとライトのバリアントを使用します。

ダークテーマとライトテーマを少なくとも1つずつ提供すると、Starlightは自動的にアクティブなコードブロックのテーマを現在のサイトテーマと同期します。この動作はuseStarlightDarkModeSwitchオプションから設定できます。

`useStarlightDarkModeSwitch`

type: boolean
default: true

trueの場合、サイトテーマが変更されると、コードブロックは自動的にライトテーマとダークテーマを切り替えます。falseの場合、複数のテーマの切り替えをおこなうために、手動でCSSを追加する必要があります。

`useStarlightUiThemeColors`

type: boolean
default: themesが設定されていない場合はtrue、それ以外の場合はfalse

trueの場合、コードブロックのUI要素（背景、ボタン、シャドウなど）の色にStarlightのCSS変数が使用され、サイトのカラーテーマと一致させます。falseの場合、これらの要素には、アクティブなシンタックスハイライトのテーマから提供される色が使用されます。

`pagefind`

type: boolean | PagefindOptions
default: true

Starlightのデフォルトのサイト検索プロバイダであるPagefindを設定します。

falseに設定すると、Pagefindによるサイトのインデックス作成はおこなわれません。また、デフォルトの検索UIを使用している場合は、これも非表示になります。

prerenderオプションがfalseに設定されている場合、Pagefindを有効にすることはできません。

Pagefindの検索クライアントを設定するには、pagefindにオブジェクトを設定します。

検索結果のランキングの計算方法を制御するpagefind.rankingオプションの使用方法については、Pagefindドキュメントの「Customize Pagefind’s result ranking」を参照してください。
複数サイトの検索方法を制御するpagefind.mergeIndexオプションの使用方法については、Pagefindドキュメントの「Searching multiple sites」を参照してください。

`PagefindOptions`

interface PagefindOptions {
  ranking?: {
    pageLength?: number;
    termFrequency?: number;
    termSaturation?: number;
    termSimilarity?: number;
  };
  indexWeight?: number;
  mergeIndex?: Array<{
    bundlePath: string;
    indexWeight?: number;
    basePath?: string;
    baseUrl?: string;
    mergeFilter?: Record<string, string | string[]>;
    language?: string;
    ranking?: {
      pageLength?: number;
      termFrequency?: number;
      termSaturation?: number;
      termSimilarity?: number;
    };
  }>;
}

`prerender`

type: boolean
default: true

Starlightページが静的HTMLに事前レンダリングされるか、SSRアダプターによってオンデマンドでレンダリングされるかを設定します。

Starlightページはデフォルトで事前レンダリングされます。SSRアダプターを使用してStarlightページをオンデマンドでレンダリングしたい場合は、prerender: falseに設定します。

`head`

type: HeadConfig[]

Starlightサイトの<head>にカスタムタグを追加します。アナリティクスやその他のサードパーティのスクリプトやリソースを追加するのに便利です。

starlight({
  head: [
    // Fathomのアナリティクススクリプトタグを追加する例。
    {
      tag: 'script',
      attrs: {
        src: 'https://cdn.usefathom.com/script.js',
        'data-site': 'MY-FATHOM-ID',
        defer: true,
      },
    },
  ],
});

headのエントリーは直接HTML要素に変換され、Astroのスクリプトやスタイルの処理を通過しません。スクリプト、スタイル、または画像などのローカルアセットをインポートする必要がある場合は、Headコンポーネントをオーバーライドしてください。

`HeadConfig`

interface HeadConfig {
  tag: string;
  attrs?: Record<string, string | boolean | undefined>;
  content?: string;
}

`lastUpdated`

type: boolean
default: false

フッターにページの最終更新日を表示するかどうかを制御します。

デフォルトでは、この機能はリポジトリのGit履歴に依存しており、浅いクローンを実行する一部のデプロイプラットフォームでは正確にならない場合があります。フロントマターのlastUpdatedフィールドを使用して、各ページでこの設定またはGitを基準とした日付を上書きできます。

`pagination`

type: boolean
default: true

フッターに前のページと次のページへのリンクを含めるかどうかを定義します。

prevとnextフロントマターフィールドを使用して、この設定、またはリンクテキストとURLをページごとに上書きできます。

`favicon`

type: string
default: '/favicon.svg'

サイトのデフォルトファビコンのパスを設定します。ファビコンはpublic/ディレクトリに配置され、また有効なアイコンファイル（.ico、.gif、.jpg、.png、または.svg）である必要があります。

starlight({
  favicon: '/images/favicon.svg',
}),

追加のバリアントやフォールバック用のファビコンを設定する必要がある場合は、headオプションを使用してタグを追加できます。

starlight({
  favicon: '/images/favicon.svg',
  head: [
    // Safari用にICOファビコンのフォールバックを追加します。
    {
      tag: 'link',
      attrs: {
        rel: 'icon',
        href: '/images/favicon.ico',
        sizes: '32x32',
      },
    },
  ],
});

`titleDelimiter`

type: string
default: '|'

ブラウザのタブに表示される、ページの<title>タグ内のページタイトルとサイトタイトルの間の区切り文字を設定します。

デフォルトでは、すべてのページの<title>はページタイトル | サイトタイトルとなります。たとえば、このページのタイトルは「設定方法」であり、このサイトのタイトルは「Starlight」なので、このページの<title>は「設定方法 | Starlight」となります。

`disable404Route`

type: boolean
default: false

Starlightのデフォルトの404ページを無効にします。プロジェクトでカスタムのsrc/pages/404.astroルートを使用するには、このオプションをtrueに設定します。

`routeMiddleware`

type: string | string[]

Starlightがデータを処理する方法を変更できるルートミドルウェアへのパスを指定します。これらのファイルパスは、Astroのミドルウェアと競合してはなりません。

ルートミドルウェアの作成方法の詳細については、ルートデータガイドを参照してください。

`components`

type: Record<string, string>

コンポーネントへのパスを指定して、Starlightのデフォルトの実装をオーバーライドします。

starlight({
  components: {
    SocialLinks: './src/components/MySocialLinks.astro',
  },
});

オーバーライド可能なすべてのコンポーネントの詳細については、オーバーライドリファレンスを参照してください。

`plugins`

type: StarlightPlugin[]

Starlightをカスタムプラグインにより拡張します。プラグインは、Starlightの機能を変更または追加するために、プロジェクトに変更を適用します。

利用可能なプラグインの一覧については、プラグインショーケースを参照してください。

starlight({
  plugins: [starlightPlugin()],
});

独自のプラグインを作成する方法の詳細については、プラグインリファレンスを参照してください。

`credits`

type: boolean
default: false

「Starlightで作成」リンクをサイトのフッターに表示します。

starlight({
  credits: true,
});

コンテンツコレクションの設定

Starlightは、Astroのコンテンツコレクションを使用してコンテンツを読み込みます。Starlightのコンテンツローダーとスキーマにより、必要に応じてコレクションを設定できます。

import { defineCollection } from 'astro:content';
import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  // 任意: i18nコレクションは多言語サイトのUI翻訳に使用されます
  i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }),
};

ローダー

Starlightは、コンテンツコレクションの設定をシンプルにするために、@astrojs/starlight/loadersモジュールから以下のAstroローダーをエクスポートしています。

`docsLoader()`

docsLoader()は、src/content/docs/ディレクトリからローカルのMarkdown、MDX、Markdocファイルを読み込みます。アンダースコア（_）で始まるファイル名は無視されます。

インポート

import { docsLoader } from '@astrojs/starlight/loaders';

オプション

`generateId()`

type: ({ entry: string; base: URL; data: Record<string, unknown> }) => string

デフォルトでは、docsLoader()を使用して生成されたページは、ファイル名にスラッグ化処理を施し、特殊文字を削除してファイル名を小文字に変換します。このデフォルトの動作をオーバーライドしたい場合は、独自のgenerateId()関数を指定してください。

たとえば、デフォルトでは削除される特殊文字を保持したい場合に便利です。デフォルトでは、Example.File.mdは/examplefileとして配信されます。/Example.Fileとして配信したい場合は、カスタムのgenerateId()関数を定義することで実現できます。

docsLoader({
  // `.md`または`.mdx`拡張子を削除し、それ以外のファイル名は処理しない。
  generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),

詳細については、AstroドキュメントのgenerateId()を参照してください。

`i18nLoader()`

i18nLoader()は、src/content/i18n/ディレクトリからローカルのJSONおよびYAMLファイルを読み込みます。アンダースコア（_）で始まるファイル名は無視されます。

インポート

import { i18nLoader } from '@astrojs/starlight/loaders';

オプション

現在、i18nLoader()に設定可能なオプションはありません。

スキーマ

Starlightは、@astrojs/starlight/schemaモジュールから以下のコンテンツコレクションスキーマを提供しています。これらのスキーマは、Starlightが依存するdocsおよびi18nコレクションに使用する必要があります。

`docsSchema()`

docsSchema()は、docsコレクション内のすべてのコンテンツのフロントマターを解析します。

インポート

import { docsSchema } from '@astrojs/starlight/schema';

オプション

`extend`

type: Zodスキーマ、またはZodスキーマを返す関数 default: z.object({})

Starlightのフロントマタースキーマを追加フィールドで拡張します。extendオプションの使用方法の詳細については、「フロントマタースキーマをカスタマイズする」を参照してください。

`i18nSchema()`

i18nSchema()は、i18nコレクション内のすべてのデータファイルを解析します。

インポート

import { i18nSchema } from '@astrojs/starlight/schema';

オプション

`extend`

type: Zodオブジェクト default: z.object({})

Starlightのi18nスキーマを追加フィールドで拡張します。extendオプションの使用方法の詳細については、「翻訳スキーマを拡張する」を参照してください。

設定方法

starlightインテグレーションの設定

title（必須）

description

logo

LogoConfig

tableOfContents

editLink

sidebar

並び順

グループの折りたたみ

ラベルの翻訳

SidebarItem

BadgeConfig

locales

LocaleConfig

label（必須）

lang

dir

ルートロケール

defaultLocale

social

customCss

markdown

headingLinks

processedDirs

expressiveCode

themes

useStarlightDarkModeSwitch

useStarlightUiThemeColors

pagefind

PagefindOptions

prerender

head

HeadConfig

lastUpdated

pagination

favicon

titleDelimiter

disable404Route

routeMiddleware

components

plugins

credits

コンテンツコレクションの設定

ローダー

docsLoader()

インポート

オプション

generateId()

i18nLoader()

インポート

オプション

スキーマ

docsSchema()

インポート

オプション

extend

i18nSchema()

インポート

オプション

extend

`starlight`インテグレーションの設定

`title`（必須）

`description`

`logo`

`LogoConfig`

`tableOfContents`

`editLink`

`sidebar`

`SidebarItem`

`BadgeConfig`

`locales`

`LocaleConfig`

`label`（必須）

`lang`

`dir`

`defaultLocale`

`social`

`customCss`

`markdown`

`headingLinks`

`processedDirs`

`expressiveCode`

`themes`

`useStarlightDarkModeSwitch`

`useStarlightUiThemeColors`

`pagefind`

`PagefindOptions`

`prerender`

`head`

`HeadConfig`

`lastUpdated`

`pagination`

`favicon`

`titleDelimiter`

`disable404Route`

`routeMiddleware`

`components`

`plugins`

`credits`

`docsLoader()`

`generateId()`

`i18nLoader()`

`docsSchema()`

`extend`

`i18nSchema()`

`extend`