Starlightのカスタマイズ
Starlightには標準的なスタイルと機能がデフォルトで用意されているため、設定不要ですぐに使い始めることができますが、Starlightサイトの見た目をカスタマイズしたくなった場合は、このガイドを参照してください。
ロゴを追加する
カスタムロゴをサイトヘッダーに設定して、Starlightサイトに個別のブランディングを追加することができます。
-
ロゴ画像のファイルを
src/assets/
ディレクトリに追加します。ディレクトリsrc/
ディレクトリassets/
- my-logo.svg
ディレクトリcontent/
- …
- astro.config.mjs
-
astro.config.mjs
で、Starlightのlogo.src
オプションにロゴのパスを指定します。
デフォルトでは、ロゴはサイトのtitle
と一緒に表示されます。ロゴ画像にサイトタイトルが含まれている場合は、replacesTitle
オプションを設定して、タイトルテキストを非表示にすることができます。title
テキストはスクリーンリーダーのために残されるので、ヘッダーはアクセシブルなままです。
ライトモードとダークモード
ライトモードとダークモードで異なるバージョンのロゴを表示することができます。
-
src/assets/
に各バージョンの画像ファイルを追加します。ディレクトリsrc/
ディレクトリassets/
- light-logo.svg
- dark-logo.svg
ディレクトリcontent/
- …
- astro.config.mjs
-
astro.config.mjs
で、src
ではなくlight
とdark
オプションにロゴのパスを指定します。
サイトマップを有効化する
Starlightにはサイトマップ生成機能が組み込まれています。astro.config.mjs
のsite
にURLを設定すると、サイトマップの生成が有効になります。
ページレイアウト
Starlightのページはデフォルトで、グローバルなナビゲーションサイドバーと、現在のページの見出しを表示する目次を配置したレイアウトを使用します。
ページのフロントマターでtemplate: splash
を設定することで、サイドバーのない、より広いページレイアウトを適用できます。これはランディングページに特に適しており、このサイトのホームページで確認することができます。
目次
Starlightは、目当ての見出しに読者が簡単にジャンプできるように、各ページに目次を表示します。目次は、Starlightインテグレーションでグローバルにカスタマイズ・無効化できます。また、フロントマターでページごとの設定も可能です。
デフォルトでは、目次には<h2>
と<h3>
の見出しが含まれます。目次に含める見出しレベルをサイト全体で変更するには、グローバルなtableOfContents
のminHeadingLevel
とmaxHeadingLevel
オプションを使用します。個々のページでこれらのデフォルト値を上書きするには、対応するフロントマターのtableOfContents
プロパティを追加します。
tableOfContents
オプションをfalse
に設定することで、目次を完全に無効にできます。
ソーシャルリンク
Starlightは、Starlightインテグレーションのsocial
オプションを使用して、サイトヘッダーにソーシャルメディアアカウントへのリンクを追加する機能を備えています。
設定方法のリファレンスで、サポートされているリンクアイコンの完全なリストを確認できます。他のサービスのサポートが必要な場合は、GitHubかDiscordでお知らせください!
編集リンク
Starlightは、各ページのフッターに「ページを編集」リンクを表示できます。これにより読者は、ドキュメントを改善するために編集すべきファイルを簡単に見つけられます。特にオープンソースプロジェクトでは、コミュニティからの貢献を促すのに役立ちます。
編集リンクを有効にするには、Starlightインテグレーションの設定で、editLink.baseUrl
をリポジトリの編集に使用するURLに設定します。editLink.baseUrl
の値は現在のページへのパスの先頭に追加されて、最終的な編集リンクを形成します。
よくあるパターンは以下の通りです。
- GitHub:
https://github.com/USER_NAME/REPO_NAME/edit/BRANCH_NAME/
- GitLab:
https://gitlab.com/USER_NAME/REPO_NAME/-/edit/BRANCH_NAME/
Starlightプロジェクトがリポジトリのルートにない場合は、ベースURLの末尾にプロジェクトへのパスを含めます。
以下の例では、GitHub上にあるwithastro/starlight
リポジトリのmain
ブランチのdocs/
サブディレクトリに置かれている、Starlightドキュメントの編集リンクを設定しています。
カスタム404ページ
Starlightサイトは、デフォルトでシンプルな404ページを表示します。これは、src/content/docs/
ディレクトリに404.md
(または404.mdx
)ファイルを追加することでカスタマイズできます。
ディレクトリsrc/
ディレクトリcontent/
ディレクトリdocs/
- 404.md
- index.md
- astro.config.mjs
404ページでは、Starlightのページレイアウトとカスタマイズ機能をすべて使用できます。たとえば、デフォルトの404ページは、フロントマターでsplash
テンプレートとhero
コンポーネントを使用しています。
デフォルトの404ページを無効にする
完全にカスタマイズされた404レイアウトがプロジェクトに必要な場合は、src/pages/404.astro
ルートを作成し、Starlightのデフォルトルートを無効にするためにdisable404Route
オプションを設定します。
カスタムフォント
デフォルトでは、Starlightはユーザーのローカルデバイスで利用可能なサンセリフフォントをすべてのテキストに使用します。これにより、大きなフォントファイルをダウンロードするための余分な帯域幅を必要とせず、各ユーザーに馴染みのあるフォントでドキュメントを高速に読み込むことができます。
Starlightサイトにカスタムフォントを追加する必要がある場合は、カスタムCSSファイルまたは他のAstroのスタイリング手法により使用するフォントを設定できます。
フォントの設定
フォントファイルがすでに手元にある場合は、ローカルの設定ガイドに従ってください。Google Fontsを使用するには、Fontsourceの設定ガイドに従ってください。
ローカルフォントファイルの設定
-
src/fonts/
ディレクトリにフォントファイルを追加し、空のfont-face.css
ファイルを作成します。ディレクトリsrc/
ディレクトリcontent/
- …
ディレクトリfonts/
- CustomFont.woff2
- font-face.css
- astro.config.mjs
-
src/fonts/font-face.css
に、各フォントの@font-face
宣言を追加します。url()
関数にフォントファイルへの相対パスを指定します。 -
astro.config.mjs
で、StarlightのcustomCss
配列にfont-face.css
ファイルへのパスを追加します。
Fontsourceフォントの設定
Fontsourceプロジェクトは、Google Fontsやその他のオープンソースフォントの使用を容易にします。使いたいフォントのnpmモジュールをインストールすることができ、プロジェクトに追加するためのCSSファイルも用意されています。
-
Fontsourceのカタログで使用したいフォントを見つけます。この例では、IBM Plex Serifを使用します。
-
使いたいフォントのパッケージをインストールします。Fontsourceのフォントページで「Install」をクリックすると、パッケージ名が表示されます。
-
astro.config.mjs
で、FontsourceのCSSファイルをStarlightのcustomCss
配列に追加します。Fontsourceは、各フォント用に複数のCSSファイルを同梱しています。異なるウェイトやスタイルを含める方法については、Fontsourceのドキュメントを参照してください。
フォントを使う
設定したフォントをサイトに適用するには、選択したフォントの名前をカスタムCSSファイルで指定します。たとえば、Starlightのデフォルトフォントをすべての場所で上書きするには、--sl-font
カスタムプロパティを設定します。
フォントをもっと部分的に適用したい場合は、よりターゲットを絞ったCSSを書くこともできます。たとえば、メインコンテンツにのみフォントを設定し、サイドバーには設定しない場合は、次のようにします。
サイトにスタイルを追加するには、カスタムCSSの導入手順に従ってください。