コンテンツにスキップ

設定方法

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

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

astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
export default defineConfig({
integrations: [
starlight({
title: '私の楽しいドキュメントサイト',
}),
],
});

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

title(必須)

type: string

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

description

type: string

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

type: LogoConfig

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

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>の見出しがこの目次に含まれます。

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を指す編集リンクが表示されます。

type: SidebarItem[]

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

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

  • link — 特定のURL、たとえば'/home''https://example.com'などへの単一のリンク。

  • items — サイドバーの複数のリンクとサブグループを含む配列。

  • autogenerate — リンクのグループを自動的に生成するために、ドキュメントのディレクトリを指定するオブジェクト。

starlight({
sidebar: [
// 「ホーム」というラベルのついた単一のリンク。
{ label: 'ホーム', link: '/' },
// 2つのリンクを含む、「ここから始める」というラベルのついたグループ。
{
label: 'ここから始める',
items: [
{ label: 'はじめに', link: '/intro' },
{ label: '次のステップ', link: '/next-steps' },
],
},
// referenceディレクトリのすべてのページにリンクするグループ。
{
label: 'リファレンス',
autogenerate: { directory: 'reference' },
},
],
});

並び順

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

グループの折りたたみ

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

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

sidebar: [
// 折りたたまれたリンクのグループ。
{
label: '折りたたまれたリンク',
collapsed: true,
items: [
{ label: 'はじめに', link: '/intro' },
{ label: '次のステップ', link: '/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 = {
label: string;
translations?: Record<string, string>;
badge?: string | BadgeConfig;
} & (
| {
link: string;
attrs?: Record<string, string | number | boolean | undefined>;
}
| { items: SidebarItem[]; collapsed?: boolean }
| {
autogenerate: { directory: string; collapsed?: boolean };
collapsed?: boolean;
}
);

BadgeConfig

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

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: Partial<Record<'bitbucket' | 'codeberg' | 'codePen' | 'discord' | 'email' | 'facebook' | 'github' | 'gitlab' | 'gitter' | 'instagram' | 'linkedin' | 'mastodon' | 'matrix' | 'microsoftTeams' | 'openCollective' | 'patreon' | 'reddit' | 'rss' | 'slack' | 'stackOverflow' | 'telegram' | 'threads' | 'twitch' | 'twitter' | 'x.com' | 'youtube', string>>

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

starlight({
social: {
codeberg: 'https://codeberg.org/knut/examples',
discord: 'https://astro.build/chat',
github: 'https://github.com/withastro/starlight',
gitlab: 'https://gitlab.com/delucis',
linkedin: 'https://www.linkedin.com/company/astroinc',
mastodon: 'https://m.webtoo.ls/@astro',
threads: 'https://www.threads.net/@nmoodev',
twitch: 'https://www.twitch.tv/bholmesdev',
twitter: 'https://twitter.com/astrodotbuild',
'x.com': 'https://x.com/astrodotbuild',
youtube: 'https://youtube.com/@astrodotbuild',
},
});

customCss

type: string[]

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

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

starlight({
customCss: ['./src/custom-styles.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を上書きできます。これにより、コードブロックに角丸を付けるなどのカスタマイズが可能になります。

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
default: true

Starlightのデフォルトのサイト検索プロバイダであるPagefindを有効にするかどうかを定義します。

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

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

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

prevnextフロントマターフィールドを使用して、この設定、またはリンクテキストと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に設定します。

components

type: Record<string, string>

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

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

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

plugins

type: StarlightPlugin[]

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

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

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

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