Starlight を利用してサイトを立ち上げる

Starlight とは？

簡単なドキュメントサイトを立ち上げる際に、Starlight は最適です。ドキュメント自体は Markdown で書くことができ、またドキュメントサイト向けに必要な機能が一通り揃っています。

Starlight は Astro のテンプレートとして提供されており、サイトでの表示も高速、そしてホスティングする際にも様々なサービスに対応しています。

詳しくは、公式サイトをご覧ください。

• Starlight 公式サイト

Starlight のプロジェクト作成

新しいプロジェクトを作成します。今回は個人的に使い慣れている Tailwind CSS を利用できるテンプレートを選択します。

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

この記事を書いているタイミングでは、以下のバージョンとなりました。

• Astro 5.6.1
• Starlight 0.37.0
• Tailwind CSS 4.0.7

完成したプロジェクトにはサンプルのコードが含まれています。次のコマンドで実行します。

npm run dev

サンプルのコードでサイトが立ち上がりました。

サイトの多言語化

Starlight は多言語サイトにも対応しています。言語切り替えなども含めて簡単に実装することが可能です。

この設定は、astro.config.mjs のファイルに設定を追加するだけで有効になります。今回はルートを日本語、英語は /en というパスで表示するようにします。また左側に表示するラベルなども翻訳のリソースを追加します。以下がサンプルのコードになります。

export default defineConfig({
  integrations: [
    starlight({
      title: "Docs with Tailwind",
      social: [
        {
          icon: "github",
          label: "GitHub",
          href: "https://github.com/haramizu/starlight-sample",
        },
      ],
      defaultLocale: "root",
      locales: {
        root: {
          label: "日本語",
          lang: "ja",
        },
        en: {
          label: "English",
          lang: "en",
        },
      },
      sidebar: [
        {
          label: "ガイド",
          translations: {
            en: "Guides",
          },
          autogenerate: { directory: "guides" },
        },
        {
          label: "参照",
          translations: {
            en: "References",
          },
          autogenerate: { directory: "reference" },
        },
      ],
      customCss: ["./src/styles/global.css"],
    }),
  ],

下のサンプルのコンテンツを src/content/docs/en にコピーをして、画像のパス、日本語のリソースを翻訳して切り替えるなどコンテンツの調整も実施したあと、改めて起動します。右上に言語切り替えのドロップダウンが追加されているのを確認することができます。

これで多言語化に関しては完了です。

Sitemap / robots.txt の作成

作成したサイトのサイトマップを利用できるように、Sitemap の機能を有効にします。非常にシンプルで、公開をするサイトの URL を設定するだけです。

export default defineConfig({
  site: "https://haramizu-starlight-sample.vercel.app",
  integrations: [

この設定をした後、一度サイトの Build を実行してください。

npm run build

実際に build を実行すると以下の２つのファイルが作成されています。

• dist/sitemap-index.xml
• dist/sitemap-0.xml

sitemap-index.xml のファイルに関しては、robots.txt に対してパスを設定する必要が出てきます。今回は public/robots.txt のファイルを作成して、以下のように記述しました。

User-agent: *
Allow: /

Sitemap: https://haramizu-starlight-sample.vercel.app/sitemap-index.xml

これでサイトマップおよび robots.txt の設定が完了しました。

Prettier を追加する

Prettier は、コードのフォーマットを自動的に整えるためのツールです。これにより、コードの一貫性を保ち、読みやすさを向上させることができます。以下のコマンドで Prettier をインストールします。

npm install --save-dev prettier prettier-plugin-astro

Tailwind CSS の設定も追加します。

npm install --save-dev prettier-plugin-tailwindcss

上記のパッケージをインストール後、プロジェクトのルートディレクトリに .prettierrc.json のファイルを作成し、設定を追加します。

{
  "endOfLine": "crlf",
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 100,
  "plugins": ["prettier-plugin-astro", "prettier-plugin-tailwindcss"],
  "overrides": [
    {
      "files": "*.astro",
      "options": {
        "parser": "astro"
      }
    }
  ]
}

これで、Prettier を利用してコードのフォーマットを統一する準備が整いました。

まとめ

今回は Astro / Starlight を利用してサイトを立ち上げる手順を紹介しました。基本的には公式サイトのガイダンスを参照しつつ進めただけです。Astro を展開できるサイトであれば Vercel でも Netlify でも、GitHub にも展開できます。

サンプルのコードを以下のリポジトリに公開してあります。

• https://github.com/haramizu/starlight-sample