設定方法
starlight
インテグレーションの設定
StarlightはAstroウェブフレームワークの上に構築されたインテグレーションです。astro.config.mjs
設定ファイル内でプロジェクトの設定をおこないます。
以下のオプションをstarlight
インテグレーションに設定できます。
title
(必須)
type: string
ウェブサイトのタイトルを設定します。メタデータとブラウザのタブのタイトルに使用されます。
description
type: string
ウェブサイトの説明を設定します。description
がページのフロントマターに設定されていない場合、<meta name="description">
タグで検索エンジンに共有するメタデータとして使用されます。
logo
type: LogoConfig
ナビゲーションバーにサイトタイトルと並べて、またはその代わりとして表示するロゴ画像を設定します。単一のsrc
プロパティを設定するか、light
とdark
用に別々の画像ソースを設定できます。
LogoConfig
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
リポジトリのページを編集するには以下のようにします。
この設定により、/introduction
ページにはhttps://github.com/withastro/starlight/edit/main/src/content/docs/introduction.md
を指す編集リンクが表示されます。
sidebar
type: SidebarItem[]
サイトのサイドバーのナビゲーション項目を設定します。
サイドバーはリンクとリンクのグループの配列です。各項目は、label
と以下のプロパティのいずれかが必要です。
-
link
— 特定のURL、たとえば'/home'
や'https://example.com'
などへの単一のリンク。 -
items
— サイドバーの複数のリンクとサブグループを含む配列。 -
autogenerate
— リンクのグループを自動的に生成するために、ドキュメントのディレクトリを指定するオブジェクト。
並び順
自動生成されたサイドバーグループは、ファイル名のアルファベット順に並べ替えられます。たとえば、astro.md
から生成されたページは、starlight.md
というページの上に表示されます。
グループの折りたたみ
リンクのグループはデフォルトで展開されます。collapsed
プロパティをtrue
に設定して、この動作を変更できます。
自動生成されたサブグループは、デフォルトでは親グループのcollapsed
プロパティに従います。autogenerate.collapsed
プロパティを設定して、これを上書きできます。
ラベルの翻訳
多言語対応が必要なサイトの場合、各項目のlabel
はデフォルトのロケールのものとみなされます。サポート対象の言語のラベルを提供するには、translations
プロパティを設定します。
SidebarItem
BadgeConfig
locales
type: { [dir: string]: LocaleConfig }
サイトの国際化(i18n)をおこなうには、サポート対象のlocales
を設定します。
各エントリは、その言語のファイルが保存されているディレクトリ名をキーとして使用する必要があります。
LocaleConfig
各ロケールに対し以下のオプションを設定できます。
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/
ディレクトリなしでデフォルト言語を提供できます。
この設定により、たとえば/getting-started/
を英語のルートとし、対応するフランス語のページを/fr/getting-started/
として提供することができます。
defaultLocale
type: string
このサイトのデフォルト言語を設定します。この値は、locales
オブジェクトのキーのいずれかと一致する必要があります。(デフォルト言語がルートロケールの場合は、この設定をスキップできます。)
翻訳がない場合には、デフォルトロケールがフォールバックコンテンツとして使用されます。
social
type: Partial<Record<'bitbucket' | 'codeberg' | 'codePen' | 'discord' | 'email' | 'facebook' | 'github' | 'gitlab' | 'gitter' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'openCollective' | 'patreon' | 'reddit' | 'rss' | 'signal' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'twitch' | 'twitter' | 'x.com' | 'youtube', string>>
このサイトのソーシャルメディアアカウントに関する任意の項目です。これらのいずれかを追加すると、サイトヘッダーにアイコンリンクとして表示されます。
customCss
type: string[]
Starlightサイトの見た目をカスタマイズするためのCSSファイルを設定します。
プロジェクトのルートからの相対パスで指定したローカルのCSSファイル('./src/custom.css'
など)と、npmモジュールとしてインストールしたCSS('@fontsource/roboto'
など)に対応しています。
expressiveCode
type: StarlightExpressiveCodeOptions | boolean
default: true
Starlightは、Expressive Codeを使用して、コードブロックのレンダリングやコード例の一部のハイライト、コードブロックへのファイル名の追加などをおこなっています。MarkdownやMDXのコンテンツでExpressive Code構文を使用する方法については、「コードブロック」ガイドを参照してください。
Expressive Code標準の設定オプションはすべて使用できます。また、StarlightのexpressiveCode
オプションを設定することで、Starlight固有のプロパティも使用できます。たとえば、Expressive CodeのstyleOverrides
オプションを設定して、デフォルトのCSSを上書きできます。これにより、コードブロックに角丸を付けるなどのカスタマイズが可能になります。
Expressive Codeを無効にするには、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
default: true
Starlightのデフォルトのサイト検索プロバイダであるPagefindを有効にするかどうかを定義します。
false
に設定すると、Pagefindによるサイトのインデックス作成はおこなわれません。また、デフォルトの検索UIを使用している場合は、これも非表示になります。
head
type: HeadConfig[]
Starlightサイトの<head>
にカスタムタグを追加します。アナリティクスやその他のサードパーティのスクリプトやリソースを追加するのに便利です。
head
のエントリーは直接HTML要素に変換され、Astroのスクリプトやスタイルの処理を通過しません。スクリプト、スタイル、または画像などのローカルアセットをインポートする必要がある場合は、Headコンポーネントをオーバーライドしてください。
HeadConfig
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
)である必要があります。
追加のバリアントやフォールバック用のファビコンを設定する必要がある場合は、head
オプションを使用してタグを追加できます。
titleDelimiter
type: string
default: '|'
ブラウザのタブに表示される、ページの<title>
タグ内のページタイトルとサイトタイトルの間の区切り文字を設定します。
デフォルトでは、すべてのページの<title>
はページタイトル | サイトタイトル
となります。たとえば、このページのタイトルは「設定方法」であり、このサイトのタイトルは「Starlight」なので、このページの<title>
は「設定方法 | Starlight」となります。
disable404Route
type: boolean
default: false
Starlightのデフォルトの404ページを無効にします。プロジェクトでカスタムのsrc/pages/404.astro
ルートを使用するには、このオプションをtrue
に設定します。
components
type: Record<string, string>
コンポーネントへのパスを指定して、Starlightのデフォルトの実装をオーバーライドします。
オーバーライド可能なすべてのコンポーネントの詳細については、オーバーライドリファレンスを参照してください。
plugins
type: StarlightPlugin[]
Starlightをカスタムプラグインにより拡張します。プラグインは、Starlightの機能を変更または追加するために、プロジェクトに変更を適用します。
利用可能なプラグインの一覧については、プラグインショーケースを参照してください。
独自のプラグインを作成する方法の詳細については、プラグインリファレンスを参照してください。