CSSとスタイリング

カスタムCSSファイルやStarlightのTailwindプラグインを使用して、Starlightサイトをスタイリングできます。

サイトのデフォルトスタイルを手軽に変更するには、コミュニティテーマを確認してください。

カスタムCSSスタイル

Starlightサイトに適用されるスタイルをカスタマイズするには、追加のCSSファイルを作成し、Starlightのデフォルトスタイルを変更または拡張します。

src/ディレクトリにCSSファイルを追加します。たとえば、以下ではデフォルトのカラム幅を広げ、ページタイトルのテキストサイズを大きくしています。
src/styles/custom.css
```
:root {
  --sl-content-width: 50rem;
  --sl-text-5xl: 3.5rem;
}
```

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

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'カスタムCSSを設定したドキュメント',
      customCss: [
        // カスタムCSSファイルへの相対パス
        './src/styles/custom.css',
      ],
    }),
  ],
});

GitHub上のprops.cssファイルで、サイトをカスタマイズするために設定可能な、Starlightが使用しているすべてのカスタムCSSプロパティを確認できます。

カスケードレイヤー

Starlightは内部でカスケードレイヤーを使用して、スタイルの適用順序を管理しています。これにより、CSSの適用順序が予測可能になり、またスタイルの上書きが容易になります。レイヤーに属さないカスタムCSSは、Starlightのスタイルを上書きします。

カスケードレイヤーを使用する場合は、カスタムCSSで@layerを使用して、starlightレイヤーのスタイルに対する各レイヤーの優先順位を定義できます。

@layer my-reset, starlight, my-overrides;

上の例では、my-resetというカスタムレイヤーはすべてのStarlightレイヤーの前に適用され、my-overridesというカスタムレイヤーはすべてのStarlightレイヤーの後に適用されます。my-overridesレイヤー内のスタイルはStarlightのスタイルよりも優先されますが、my-resetレイヤーに設定されたスタイルはStarlightによって変更される可能性があります。

Tailwind CSS

AstroプロジェクトでのTailwind CSS v4のサポートは、TailwindのViteプラグインによって提供されています。また、Starlightは、Starlightのスタイルとの互換性を保ちつつTailwindを設定するのに役立つ、補完的なCSSを提供しています。

StarlightのTailwind CSSは、以下の設定を適用します。

Tailwindのdark:バリアントをStarlightのダークモードと連携するように設定します。
StarlightのUIでTailwindのテーマカラーとフォントを使用します。
TailwindのPreflightリセットスタイルのうち、必要な部分を復元します。

Tailwindを使用して新しいプロジェクトを作成する

create astroを使用して、Tailwind CSSが組み込まれた新しいStarlightプロジェクトを開始します。

npm create astro@latest -- --template starlight/tailwind

pnpm create astro --template starlight/tailwind

yarn create astro --template starlight/tailwind

Tailwindを既存のプロジェクトに追加する

既存のStarlightサイトにTailwind CSSを追加する場合は、以下の手順に従ってください。

以下のコマンドを実行し、ターミナルの指示に従って、プロジェクトにTailwindをセットアップします。
- npm
- pnpm
- Yarn
Terminal window
npx astro add tailwind
Terminal window
pnpm astro add tailwind
Terminal window
yarn astro add tailwind
StarlightのTailwind互換パッケージをインストールします。
- npm
- pnpm
- Yarn
Terminal window
npm install @astrojs/starlight-tailwind
Terminal window
pnpm add @astrojs/starlight-tailwind
Terminal window
yarn add @astrojs/starlight-tailwind
Astroによって生成されたsrc/styles/global.cssファイルの内容を、Starlightとの互換性のために以下のように置き換えます。
src/styles/global.css
```
@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);
```
このTailwindテーマの設定は、Starlightのカスケードレイヤーの順序を定義し、StarlightのTailwind補完CSSをインポートし、Tailwindのテーマとユーティリティスタイルをインポートします。プロジェクトで追加のTailwindの設定が必要な場合は、「Tailwindの設定を複数使用する」セクションを参照してください。

Starlightの設定を更新して、customCss配列の最初のアイテムとしてTailwind CSSのファイルを追加します。

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

export default defineConfig({
  integrations: [
    starlight({
      title: 'Tailwindを使ったドキュメント',
      customCss: [
        // Tailwindのベーススタイルへのパス
        './src/styles/global.css',
      ],
    }),
  ],
  vite: { plugins: [tailwindcss()] },
});

StarlightをTailwindでスタイリングする

Tailwindを使用して新しいStarlightプロジェクトを作成した場合、または既存のStarlightプロジェクトにTailwindを追加した場合、Starlightはsrc/styles/global.cssファイルにあるTailwindテーマの設定値を使用してUIをスタイリングします。

以下のCSSカスタムプロパティが設定されている場合、Starlightのデフォルトスタイルが上書きされます。

--color-accent-* — リンクと現在のアイテムのハイライトに使用されます
--color-gray-* — 背景色とボーダーに使用されます
--font-sans — UIとコンテンツのテキストに使用されます
--font-mono — コード例に使用されます

@layer base, starlight, theme, components, utilities;

@import '@astrojs/starlight-tailwind';
@import 'tailwindcss/theme.css' layer(theme);
@import 'tailwindcss/utilities.css' layer(utilities);

@theme {
  /* 好みのテキストフォント。Starlightはデフォルトでシステムフォントスタックを使用します。 */
  --font-sans: 'Atkinson Hyperlegible';
  /* 好みのコードフォント。Starlightはデフォルトでシステムの等幅フォントを使用します。 */
  --font-mono: 'IBM Plex Mono';
  /* 好みのアクセントカラー。インディゴはStarlightのデフォルトに最も近い色です。 */
  --color-accent-50: var(--color-indigo-50);
  --color-accent-100: var(--color-indigo-100);
  --color-accent-200: var(--color-indigo-200);
  --color-accent-300: var(--color-indigo-300);
  --color-accent-400: var(--color-indigo-400);
  --color-accent-500: var(--color-indigo-500);
  --color-accent-600: var(--color-indigo-600);
  --color-accent-700: var(--color-indigo-700);
  --color-accent-800: var(--color-indigo-800);
  --color-accent-900: var(--color-indigo-900);
  --color-accent-950: var(--color-indigo-950);
  /* 好みのグレースケール。ZincはStarlightのデフォルトに最も近い色です。 */
  --color-gray-50: var(--color-zinc-50);
  --color-gray-100: var(--color-zinc-100);
  --color-gray-200: var(--color-zinc-200);
  --color-gray-300: var(--color-zinc-300);
  --color-gray-400: var(--color-zinc-400);
  --color-gray-500: var(--color-zinc-500);
  --color-gray-600: var(--color-zinc-600);
  --color-gray-700: var(--color-zinc-700);
  --color-gray-800: var(--color-zinc-800);
  --color-gray-900: var(--color-zinc-900);
  --color-gray-950: var(--color-zinc-950);
}

Tailwindの設定を複数使用する

Tailwindの設定を複数使用することで、サイトの各部分に異なるスタイルを適用できます。Starlightをサブパスで使用する場合や、サイトにカスタムページを追加する場合などに便利です。たとえば、カスタムページではTailwindのPreflightリセットスタイルを使用しつつ、StarlightページにはStarlightの互換レイヤーを適用したい場合があるでしょう。

以下のTailwind CSSの設定は、プラグインや追加設定なしでTailwindをセットアップするもので、非Starlightのページの出発点として使用できます。

/* StarlightのCSSなしでTailwindを読み込む */
@import 'tailwindcss';

Starlightページには、「Tailwindを既存のプロジェクトに追加する」に従って、好みのTailwind CSSの設定を適用します。
その他のページには、好みのTailwind CSSの設定をインポートして適用します。これは通常、レイアウトコンポーネントで行われ、そのレイアウトを共有するすべてのページでTailwindのスタイルを使用できるようになります。
src/layouts/CustomPageLayout.astro
```
---
import '../styles/custom-pages-tailwind.css';
---
```

Tailwindテーマの設定について詳しくは、Tailwind CSSのドキュメントを参照してください。

テーマの設定

Starlightのカラーテーマは、デフォルトのカスタムプロパティを上書きしてコントロールできます。これらの変数はUI全体で使用されます。テキストと背景色にはグレーシェードが使用され、リンクとナビゲーションの現在のアイテムをハイライトするためにはアクセントカラーが使用されます。

テーマカラーエディタ

以下のスライダーを使用して、Starlightのアクセントカラーとグレーカラーのパレットを変更してみましょう。ダークとライトのプレビューエリアには、結果となる色の組み合わせが表示されます。また、このページ自体も合わせて更新されるため、変更内容をプレビューできます。

コントラストレベルオプションで、WCAGによる色のコントラスト基準から満たしたいものを指定します。

変更内容に満足できたら、以下のCSSまたはTailwindコードをコピーしてプロジェクトで使用します。

プリセット

コントラストレベル

AA AAA

アクセント

色相 269

彩度 0.27

グレー

色相 270

彩度 0.016

ダークモード

本文は背景とのコントラストが高いグレーシェードで表示されます。リンクは色付けされます。目次などの一部のテキストは、コントラストが低くなります。 インラインコードは独自の背景色をもちます。

以下のCSSをカスタムCSSファイルに追加して、このテーマをサイトに適用します。

以下のCSS変数をTailwind CSSファイルの@themeブロックに追加して、このテーマをサイトに適用します。