Blog

Astro StarlightでTailwind CSSを利用する

2025/03/16

AstroのドキュメントテンプレートStarlightでTailwind CSSを使ってみたので備忘録です。

Tailwind CSSの追加

既存のStarlightプロジェクトにTailwind CSSを追加します。(新規の場合はこちら)

AstroのTailwindインテグレーションを追加：
- pnpm
- npm
- Yarn
Terminal window
pnpm astro add @astrojs/tailwind
Terminal window
npx astro add @astrojs/tailwind
Terminal window
yarn astro add @astrojs/tailwind
現在AstroではデフォルトでTailwind CSS v4をインストールします。Stralightはまだv4対応していないので上記のようにv3をインストールしています。

StarlightのTailwindプラグインをインストール：

pnpm add @astrojs/starlight-tailwind

npm install @astrojs/starlight-tailwind

yarn add @astrojs/starlight-tailwind

Tailwindのベーススタイル用のCSSファイルを作成（例：src/styles/tailwind.css）します。
src/styles/tailwind.css
```
@tailwind base;
@tailwind components;
@tailwind utilities;
```

astro.config.mjsを更新します

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

export default defineConfig({
integrations: [
    starlight({
    title: 'Tailwindを使ったドキュメント',
    customCss: [
        './src/styles/tailwind.css',
    ],
    }),
    tailwind({
    applyBaseStyles: false,
    }),
],
});

tailwind.config.mjsにStarlightのTailwindプラグインを追加します。

import starlightPlugin from '@astrojs/starlight-tailwind';

/** @type {import('tailwindcss').Config} */
export default {
content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
plugins: [starlightPlugin()],
};

Tailwindを使ったStarlightのスタイリング

StarlightはTailwindのテーマ設定値をUIで使用します。

例としてリンクなどに使われるアクセントカラーを変更する方法を紹介します。

colors.accent：リンクと現在のアイテムのハイライト

今回はtailwindの色設定を利用します。

色を確認したい場合は、Tailwind CSSの公式サイトを参照してください。

import starlightPlugin from '@astrojs/starlight-tailwind';
import colors from 'tailwindcss/colors';

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {
      colors: {
        accent: colors.red,
      },
    },
  },
  plugins: [starlightPlugin()],
};

実行すると下記のようにカラーが変更されます。

ビフォー
アフター

カスタムテーマの作成

Starlightのカラーテーマは、カスタムプロパティを上書きしてコントロールできます。

Starlightは、テーマカラーエディタを提供しています。

下記のリンクからテーマカラーエディタにアクセスできます。

Starlightテーマカラーエディタ

Astro Starlightを国際化(i18n)機能で複数言語に対応する

2025/03/16

AstroのドキュメントテンプレートStarlightを使って、複数言語に対応したので備忘録を残します。

Starlightのi18n機能

Starlightには、以下のような国際化（i18n）機能が組み込まれています。

複数言語のルーティング
フォールバックコンテンツ
右横書き（RTL）言語のフルサポート

これらの機能により、効率的に多言語サイトを構築できます。

i18nの設定方法

astro.config.mjsファイルで、サポートする言語を指定します。

デフォルトの言語(localesに入っている言語以外に対応するための言語)も設定しましょう。

私の場合は、英語（en）と日本語（ja）をサポートし、デフォルトの言語を日本語に設定しました。

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

export default defineConfig({
    integrations: [
        starlight({
            title: 'My Docs',
            defaultLocale: 'ja',
            locales: {
                en: {
                    label: 'English',
                },
                ja: {
                    label: '日本語',
                },
                // 他の言語を追加
            },
        }),
    ],
});

src/content/docs/に各言語のディレクトリを作成します：
- ディレクトリsrc/
  - ディレクトリcontent/
    …
  - ディレクトリdocs/
    ディレクトリen/
    …
    ディレクトリja/
    …
    … 他の言語ディレクトリ

各言語ディレクトリに、対応するコンテンツファイル(記事)を配置します。

同じページには同じファイル名を使用することで、言語間でページを関連付けられます。

特定の言語をパスにプレフィックスを付けずに提供したい場合、ルートロケールを設定できます。

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

export default defineConfig({
    integrations: [
        starlight({
            defaultLocale: 'root',
            locales: {
                root: {
                    label: '日本語',
                    lang: 'ja',
                },
                en: {
                    label: 'English',
                    lang: 'en',
                },
            },
        });
    ],
});

この場合、日本語のコンテンツはsrc/content/docs/直下に配置します。

ディレクトリsrc/
- ディレクトリcontent/
  - …
- ディレクトリdocs/
  - index.md (日本語のindex.md)
  - ディレクトリen/
    index.md

フォールバックコンテンツ

未翻訳のページがある場合、Starlightは自動的にデフォルト言語のコンテンツを表示し、未翻訳である旨を通知します。

これにより、コンテンツを段階的に翻訳していくことが可能になります。

UIの翻訳

StarlightのデフォルトのUI文字列も翻訳できます。src/content/i18n/に各言語のJSONファイルを作成し、翻訳を追加します。

{
  "search.label": "検索",
  "tableOfContents.onThisPage": "目次",
  // 他の翻訳キー
}

詳しくは、Starlightのドキュメントを参照してください。

Astro StarlightでWEBフォントを利用する

2025/03/16

AstroのドキュメントテンプレートStarlightでWEBフォントを使ってみたので備忘録です。

Fontsourceフォントの設定

StarlightでWEBフォントを利用する方法はいくつかありますが、ここではFontsourceを使用する方法を紹介します。

Fontsourceは、Google FontsやAdobe Fontsなどのフォントカタログからフォントを選択し、簡単にインストールできるパッケージです。

フォントパッケージのインストール

Fontsourceのページから好きなフォントのパッケージをインストールします。

例えば、Noto Sans JPを使用する場合：
- pnpm
- npm
- Yarn
Terminal window
pnpm add @fontsource-variable/noto-sans-jp
Terminal window
npm install @fontsource-variable/noto-sans-jp
Terminal window
yarn add @fontsource-variable/noto-sans-jp

astro.config.mjsの設定

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

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

export default defineConfig({
integrations: [
    starlight({
    title: 'カスタムフォントを設定したドキュメント',
    customCss: [
        '@fontsource-variable/noto-sans-jp',
    ],
    }),
],
});

フォントの適用

設定したフォントをサイトに適用するには、カスタムCSSファイルでフォント名を指定します。

全体に適用する場合

:root {
  --sl-font: 'Noto Sans JP Variable', serif;
}

特定の要素にのみ適用する場合

main {
  font-family: 'Noto Sans JP Variable', serif;
}

Tailwind CSSで適用する場合

tailwind.config.jsファイルでフォントを設定します：

import starlightPlugin from '@astrojs/starlight-tailwind';

/** @type {import('tailwindcss').Config} */
export default {
  content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
  theme: {
    extend: {
      fontFamily: {
        sans: ['Noto Sans JP Variable'],
      },
    },
  },
  plugins: [starlightPlugin()],
};

Astro Starlightでサイトマップを追加する方法

2025/03/15

AstroのテンプレートStarlightプロジェクトにサイトマップを設定したので備忘録。

Starlightでのサイトマップ設定

Starlightには、サイトマップ生成機能が組み込まれています。

サイトマップを有効にするには、astro.config.mjsファイルのsiteオプションにURLを設定するだけです。

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

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

この設定により、ビルド時に自動的にサイトマップが生成されます。

robots.txtの設定

サイトマップを設定したら、次はrobots.txtファイルにサイトマップへのリンクを追加します。

これにより、クローラーがサイトマップを見つけやすくなります。

静的なrobots.txtファイルの作成

直接robots.txtを作成する場合はこちらの方法を使います。

public/robots.txtファイルを作成し、以下の内容を追加します：

User-agent: *
Allow: /

Sitemap: https://example.com/sitemap-index.xml

動的なrobots.txtファイルの生成

astro.config.mjsのsite値を再利用して動的にrobots.txtを生成することもできます。

public/ディレクトリに静的ファイルを置く代わりに、src/pages/robots.txt.tsファイルを作成し、以下のコードを追加します：

import type { APIRoute } from 'astro';

const getRobotsTxt = (sitemapURL: URL) => `
User-agent: *
Allow: /

Sitemap: ${sitemapURL.href}
`;

export const GET: APIRoute = ({ site }) => {
  const sitemapURL = new URL('sitemap-index.xml', site);
  return new Response(getRobotsTxt(sitemapURL));
};