Starlightのカスタマイズ

Starlightには標準的なスタイルと機能がデフォルトで用意されているため、設定不要ですぐに使い始めることができますが、Starlightサイトの見た目をカスタマイズしたくなった場合は、このガイドを参照してください。

ロゴを追加する

カスタムロゴをサイトヘッダーに設定して、Starlightサイトに個別のブランディングを追加することができます。

1. ロゴ画像のファイルをsrc/assets/ディレクトリに追加します。

   • Directorysrc/

     • Directoryassets/

       • my-logo.svg
     • Directorycontent/

       • …
   • astro.config.mjs

2. astro.config.mjsで、Starlightのlogo.srcオプションにロゴのパスを指定します。

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'ロゴを設定したドキュメント',
         logo: {
           src: './src/assets/my-logo.svg',
         },
       }),
     ],
   });

デフォルトでは、ロゴはサイトのtitleと一緒に表示されます。ロゴ画像にサイトタイトルが含まれている場合は、replacesTitleオプションを設定して、タイトルテキストを非表示にすることができます。titleテキストはスクリーンリーダーのために残されるので、ヘッダーはアクセシブルなままです。

starlight({
  title: 'ロゴを設定したドキュメント',
  logo: {
    src: './src/assets/my-logo.svg',
    replacesTitle: true,
  },
}),

ライトモードとダークモード

ライトモードとダークモードで異なるバージョンのロゴを表示することができます。

1. src/assets/に各バージョンの画像ファイルを追加します。

   • Directorysrc/

     • Directoryassets/

       • light-logo.svg
       • dark-logo.svg
     • Directorycontent/

       • …
   • astro.config.mjs

2. astro.config.mjsで、srcではなくlightとdarkオプションにロゴのパスを指定します。

   starlight({
     title: 'ロゴを設定したドキュメント',
     logo: {
       light: './src/assets/light-logo.svg',
       dark: './src/assets/dark-logo.svg',
     },
   }),

サイトマップを有効化する

Starlightにはサイトマップ生成機能が組み込まれています。astro.config.mjsのsiteにURLを設定すると、サイトマップの生成が有効になります。

astro.config.mjs

export default defineConfig({
  site: 'https://stargazers.club',
  integrations: [starlight({ title: 'サイトマップを設定したサイト' })],
});

ページレイアウト

Starlightのページはデフォルトで、グローバルなナビゲーションサイドバーと、現在のページの見出しを表示する目次を配置したレイアウトを使用します。

ページのフロントマターでtemplate: splashを設定することで、サイドバーのない、より広いページレイアウトを適用できます。これはランディングページに特に適しており、このサイトのホームページで確認することができます。

src/content/docs/index.md

---
title: ランディングページ
template: splash
---

目次

Starlightは、目当ての見出しに読者が簡単にジャンプできるように、各ページに目次を表示します。目次は、Starlightインテグレーションでグローバルにカスタマイズ・無効化できます。また、フロントマターでページごとの設定も可能です。

デフォルトでは、目次には<h2>と<h3>の見出しが含まれます。目次に含める見出しレベルをサイト全体で変更するには、グローバルなtableOfContentsのminHeadingLevelとmaxHeadingLevelオプションを使用します。個々のページでこれらのデフォルト値を上書きするには、対応するフロントマターのtableOfContentsプロパティを追加します。

フロントマター

src/content/docs/example.md

---
title: 目次にH2のみを表示するページ
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---

グローバルな設定

astro.config.mjs

defineConfig({
  integrations: [
    starlight({
      title: '',
      tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
    }),
  ],
});

tableOfContentsオプションをfalseに設定することで、目次を完全に無効にできます。

フロントマター

src/content/docs/example.md

---
title: 目次のないページ
tableOfContents: false
---

グローバルな設定

astro.config.mjs

defineConfig({
  integrations: [
    starlight({
      title: '目次をグローバルに無効にしたドキュメント',
      tableOfContents: false,
    }),
  ],
});

ソーシャルリンク

Starlightは、Starlightインテグレーションのsocialオプションを使用して、サイトヘッダーにソーシャルメディアアカウントへのリンクを追加する機能を備えています。

現在、Bitbucket、Codeberg、CodePen、Discord、GitHub、GitLab、Gitter、Instagram、LinkedIn、Mastodon、Microsoft Teams、Stack Overflow、Threads、Twitch、Twitter、YouTubeへのリンクがサポートされています。他のサービスのサポートが必要な場合は、GitHubまたはDiscordでお知らせください！

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'ソーシャルリンクを設定したドキュメント',
      social: {
        discord: 'https://astro.build/chat',
        github: 'https://github.com/withastro/starlight',
      },
    }),
  ],
});

編集リンク

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ドキュメントの編集リンクを設定しています。

astro.config.mjs

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

export default defineConfig({
  integrations: [
    starlight({
      title: '編集リンクを設定したドキュメント',
      editLink: {
        baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
      },
    }),
  ],
});

カスタム404ページ

Starlightサイトは、デフォルトでシンプルな404ページを表示します。これは、src/content/docs/ディレクトリに404.md（または404.mdx）ファイルを追加することでカスタマイズできます。

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • 404.md
      • index.md
• astro.config.mjs

404ページでは、Starlightのページレイアウトとカスタマイズ機能をすべて使用できます。たとえば、デフォルトの404ページは、フロントマターでsplashテンプレートとheroコンポーネントを使用しています。

---
title: '404'
template: splash
editUrl: false
hero:
  title: '404'
  tagline: ページが見つかりませんでした。URLを確認するか、検索バーを使用してみてください。
---

カスタムフォント

デフォルトでは、Starlightはユーザーのローカルデバイスで利用可能なサンセリフフォントをすべてのテキストに使用します。これにより、大きなフォントファイルをダウンロードするための余分な帯域幅を必要とせず、各ユーザーに馴染みのあるフォントでドキュメントを高速に読み込むことができます。

Starlightサイトにカスタムフォントを追加する必要がある場合は、カスタムCSSファイルまたは他のAstroのスタイリング手法により使用するフォントを設定できます。

フォントの設定

フォントファイルがすでに手元にある場合は、ローカルの設定ガイドに従ってください。Google Fontsを使用するには、Fontsourceの設定ガイドに従ってください。

ローカルフォントファイルの設定

1. src/fonts/ディレクトリにフォントファイルを追加し、空のfont-face.cssファイルを作成します。

   • Directorysrc/

     • Directorycontent/

       • …
     • Directoryfonts/

       • CustomFont.woff2
       • font-face.css
   • astro.config.mjs

2. src/fonts/font-face.cssに、各フォントの@font-face宣言を追加します。url()関数にフォントファイルへの相対パスを指定します。

   src/fonts/font-face.css

   @font-face {
     font-family: 'カスタムフォント';
     /* ローカルフォントファイルへの相対パスを`url()`で指定します。 */
     src: url('./CustomFont.woff2') format('woff2');
     font-weight: normal;
     font-style: normal;
     font-display: swap;
   }

3. astro.config.mjsで、StarlightのcustomCss配列にfont-face.cssファイルへのパスを追加します。

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'カスタムフォントを設定したドキュメント',
         customCss: [
           // @font-face CSSファイルへの相対パス
           './src/fonts/font-face.css',
         ],
       }),
     ],
   });

Fontsourceフォントの設定

Fontsourceプロジェクトは、Google Fontsやその他のオープンソースフォントの使用を容易にします。使いたいフォントのnpmモジュールをインストールすることができ、プロジェクトに追加するためのCSSファイルも用意されています。

1. Fontsourceのカタログで使用したいフォントを見つけます。この例では、IBM Plex Serifを使用します。

2. 使いたいフォントのパッケージをインストールします。Fontsourceのフォントページで「Install」をクリックすると、パッケージ名が表示されます。

   npm

   npm install @fontsource/ibm-plex-serif

   pnpm

   pnpm install @fontsource/ibm-plex-serif

   Yarn

   yarn add @fontsource/ibm-plex-serif

3. astro.config.mjsで、FontsourceのCSSファイルをStarlightのcustomCss配列に追加します。

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';
   
   export default defineConfig({
     integrations: [
       starlight({
         title: 'カスタムフォントを設定したドキュメント',
         customCss: [
           // 標準とセミボールドのフォントウェイト用のFontsourceファイル。
           '@fontsource/ibm-plex-serif/400.css',
           '@fontsource/ibm-plex-serif/600.css',
         ],
       }),
     ],
   });

   Fontsourceは、各フォント用に複数のCSSファイルを同梱しています。異なるウェイトやスタイルを含める方法については、Fontsourceのドキュメントを参照してください。

フォントを使う

設定したフォントをサイトに適用するには、選択したフォントの名前をカスタムCSSファイルで指定します。たとえば、Starlightのデフォルトフォントをすべての場所で上書きするには、--sl-fontカスタムプロパティを設定します。

src/styles/custom.css

:root {
  --sl-font: 'IBM Plex Serif', serif;
}

フォントをもっと部分的に適用したい場合は、よりターゲットを絞ったCSSを書くこともできます。たとえば、メインコンテンツにのみフォントを設定し、サイドバーには設定しない場合は、次のようにします。

src/styles/custom.css

main {
  font-family: 'IBM Plex Serif', serif;
}

サイトにスタイルを追加するには、カスタムCSSの導入手順に従ってください。