コンテンツにスキップ
Clameyes
Blog

Astro

Astro” の投稿: 9 件

Astroを使っていてCould not find Sharp.エラーが出た時の対処法

Astroを使っていて「Could not find Sharp.」というエラーに対処したので備忘録です。

エラーの概要

Astroでビルド時に2種類のエラーが出ました。

このエラーは通常、Astroプロジェクトで画像の最適化を行おうとした際に発生し、Sharpライブラリが見つからないことが原因です。

解決方法

そのままですが、Sharpライブラリが見つからないというエラーなので、Sharpをインストールすることで解決できます。

以下の手順に従って進めてください。

  1. まず、Sharpをプロジェクトにインストールしましょう。

    Terminal window
    pnpm add sharp

  2. astro.config.mjsファイルで、Sharpが正しく設定されているか確認します。

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    

    export default defineConfig({
        image: {
            service: { entrypoint: 'astro/assets/services/sharp' },
        },
    });

  3. もし上記の手順で解決しない場合は、キャッシュをクリアしてみましょう。

    Terminal window
    pnpm store prune

  4. 最後に、依存関係を再インストールし、プロジェクトを再ビルドします。

    Terminal window
    pnpm install --force
    pnpm build

参考リンク

Astro Starlightにコメント機能(Giscus)を導入する

AstroのドキュメントテンプレートStarlightに、GitHub Discussionsを利用したコメント機能(Giscus)を導入したので備忘録を残します。

Giscusとは

Giscusは、GitHub Discussionsを利用したコメントシステムです。

軽量で、GitHub認証を使用するため、スパム対策にも優れています。

前提条件

  • Astro Starlightのウェブサイトがセットアップされていること
  • GitHubアカウントを持っていること
  • GitHub Discussionsが有効になっているリポジトリがあること

インストール手順

  1. starlight-giscusのインストール

    まず、starlight-giscusプラグインをインストールします。ターミナルで以下のコマンドを実行してください。

    Terminal window
    pnpm add starlight-giscus

  2. Giscusアプリの設定

    Giscus公式サイトで、あなたのリポジトリに対してGiscusを設定します。

    必要な情報を入力し、スクリプトコードを生成してコピーしてください。

  3. Astro設定ファイルの更新

    astro.config.mjsファイルを開き、以下のように設定を追加します。

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightGiscus from 'starlight-giscus'
    

    export default defineConfig({
        integrations: [
            starlight({
                plugins: [
                    starlightGiscus({
                        repo: 'data-repo',
                        repoId: 'data-repo-id',
                        category: 'data-category',
                        categoryId: 'data-category-id'
                    })
                ],
                title: 'My Docs',
            }),
        ],
    })

    repo、repoId、category、categoryIdの値は、Giscusの設定で生成されたものに置き換えてください。

    上記4つは必須項目ですが、他にもカスタマイズオプションがあります。詳細は後述します。

カスタマイズオプション

starlight-giscusプラグインには、以下のようなカスタマイズオプションがあります：

  • mapping (string): ページとディスカッションのマッピング方法(ディスカッションのタイトルがどうなるか)
    • pathname (デフォルト): ページのパス名
    • URL: ページのURL
    • <title>: ページのタイトル
    • og:title: ページのog:title
  • reactions (boolean): リアクション機能の有効/無効
  • inputPosition (string): 返信フォームの位置
    • bottom (デフォルト): コメントの下部
    • top: コメントの上部
  • theme (string): コメント欄のテーマ
  • lazy (boolean): 遅延ロードの有効/無効

これらのオプションを使用して、コメント機能をサイトに合わせてカスタマイズできます。

特定ページでのコメント無効化

そのままだと、下記のようなコメントを表示しなくても良いトップページなどでコメントが表示されてしまいます。

Image from Gyazo

コメントを表示したくないページがある場合は、frontmatterで制御できます。

設定手順

  1. src/content.config.tsファイルでスキーマを拡張します

    src/content.config.ts
    import { defineCollection, z } from 'astro:content'
    import { docsLoader } from '@astrojs/starlight/loaders'
    import { docsSchema } from '@astrojs/starlight/schema'
    

    export const collections = {
        docs: defineCollection({
            loader: docsLoader(),
            schema: docsSchema({
                extend: z.object({
                    giscus: z.boolean().optional().default(true),
                }),
            }),
        }),
    }

  2. コメントを無効にしたいページのfrontmatterにgiscus: falseを追加します。

    ---
    title: コメント不要なページ
    giscus: false
    ---

starlight-blogプラグインを使っている場合

starlight-blogプラグインを使っている場合は、extendの中でblogSchema(context)を呼び出して、その後にgiscusを追加してください。

また、blogのページやtagのページでgiscusを無効にしたいのでデフォルトをfalseにします。

設定手順

  1. src/content.config.tsファイルでスキーマを拡張します

    src/content.config.ts
    import { defineCollection, z } from 'astro:content'
    import { docsLoader } from '@astrojs/starlight/loaders'
    import { docsSchema } from '@astrojs/starlight/schema'
    import { blogSchema } from 'starlight-blog/schema';
    

    export const collections = {
        docs: defineCollection({
            loader: docsLoader(),
            schema: docsSchema({
                extend: (context) => blogSchema(context).extend({
                    giscus: z.boolean().optional().default(false)
                })
            }),
        }),
    }

  2. コメントを有効にしたいページのfrontmatterにgiscus: trueを追加します。

    ---
    title: コメントを入れたいページ
    date: 2025-03-17
    giscus: true
    ---

Astro Starlight(Tailwand v3)にshadcn/uiを導入する

Astro StarlightとTailwind CSSを使用したプロジェクトに、shadcn/uiを導入する方法を紹介します。

shadcn/uiは、美しくカスタマイズ可能なUIコンポーネントを提供するライブラリです。

Starlightは現状、Tailwind CSS v3を使用しているため、shadcn/uiも同様にTailwind CSS v3で導入します。

前提条件

  • 既にAstro Starlightプロジェクトが作成されていること
  • Tailwind CSS v3が導入されていること

shadcn/uiの導入

  1. プロジェクトのルートディレクトリにあるtsconfig.jsonファイルを開き、以下のコードを追加してパスを解決します：

    tsconfig.json
    {
        "compilerOptions": {
            // ...
            "baseUrl": ".",
            "paths": {
                "@/*": [
                    "./src/*"
                ]
            }
            // ...
        }
    }

  2. shadcn/uiをセットアップするために、以下のコマンドを実行します：

    Terminal window
    pnpm dlx [email protected] init

  3. このコマンドを実行すると、プロジェクトの設定に関するいくつかの質問が表示されます。

    プロジェクトに適した選択肢を選んでください。

    私は下記のように選択しました。

    Image from Gyazo

  4. reactがインストールされていない場合、以下のコマンドを実行してreactをインストールします：

    Terminal window
    pnpm astro add react

  5. shadcn/uiを追加すると下記のようにCSSが追加されます。

    src/styles/tailwind.css
    @tailwind base;
    @tailwind components;
    @tailwind utilities;
    @layer base {
    :root {
        --background: 0 0% 100%;
        --foreground: 240 10% 3.9%;
        --card: 0 0% 100%;
        --card-foreground: 240 10% 3.9%;
        --popover: 0 0% 100%;
        --popover-foreground: 240 10% 3.9%;
        --primary: 240 5.9% 10%;
        --primary-foreground: 0 0% 98%;
        --secondary: 240 4.8% 95.9%;
        --secondary-foreground: 240 5.9% 10%;
        --muted: 240 4.8% 95.9%;
        --muted-foreground: 240 3.8% 46.1%;
        --accent: 240 4.8% 95.9%;
        --accent-foreground: 240 5.9% 10%;
        --destructive: 0 84.2% 60.2%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 5.9% 90%;
        --input: 240 5.9% 90%;
        --ring: 240 10% 3.9%;
        --chart-1: 12 76% 61%;
        --chart-2: 173 58% 39%;
        --chart-3: 197 37% 24%;
        --chart-4: 43 74% 66%;
        --chart-5: 27 87% 67%;
        --radius: 0.5rem
    }
    .dark {
        --background: 240 10% 3.9%;
        --foreground: 0 0% 98%;
        --card: 240 10% 3.9%;
        --card-foreground: 0 0% 98%;
        --popover: 240 10% 3.9%;
        --popover-foreground: 0 0% 98%;
        --primary: 0 0% 98%;
        --primary-foreground: 240 5.9% 10%;
        --secondary: 240 3.7% 15.9%;
        --secondary-foreground: 0 0% 98%;
        --muted: 240 3.7% 15.9%;
        --muted-foreground: 240 5% 64.9%;
        --accent: 240 3.7% 15.9%;
        --accent-foreground: 0 0% 98%;
        --destructive: 0 62.8% 30.6%;
        --destructive-foreground: 0 0% 98%;
        --border: 240 3.7% 15.9%;
        --input: 240 3.7% 15.9%;
        --ring: 240 4.9% 83.9%;
        --chart-1: 220 70% 50%;
        --chart-2: 160 60% 45%;
        --chart-3: 30 80% 55%;
        --chart-4: 280 65% 60%;
        --chart-5: 340 75% 55%
    }
    }
    @layer base {
    * {
        @apply border-border;
    }
    body {
        @apply bg-background text-foreground;
    }
    }

    いくつかのカスタムプロパティが追加され、ダークモードのスタイルも追加されます。

    これによってStarlightのデフォルトのスタイルが上書きされます。

    適宜カスタマイズしましょう。

    ちなみに、Starlightとshadcn/uiはダークモードとライトモードの設定が逆なので入れ替えておく必要があります。

    フレームワークダークモードライトモード
    Starlight:root:root[data-theme=“light”]
    shadcn/ui.dark:root

    注記：

    • shadcn/uiの元の設定（ダークモード: .dark、ライトモード: :root）を変更しています。
    • ダークモードとライトモードの設定を統一するために、shadcn/uiの.darkを:rootに、:rootを:root[data-theme="light"]に変更しています。
    • この変更により、StarlightとshadcnのCSS設定が一致し、両フレームワークで同じセレクタを使用してダークモードとライトモードのスタイルを定義できるようになります。

コンポーネントの追加

セットアップが完了したら、shadcn/uiのコンポーネントを追加できます。

例えば、Buttonコンポーネントを追加するには以下のコマンドを実行します。

Terminal window
pnpm dlx [email protected] add button

コンポーネントの使用

追加したコンポーネントは、以下のように使用できます。

例えば、src/docs/index.mdxファイル

src/docs/index.mdx
import { Button } from "@/components/ui/button"


<Button>Click me</Button>

Astro StarlightでTailwind CSSを利用する

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

Tailwind CSSの追加

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

  1. AstroのTailwindインテグレーションを追加：

    Terminal window
    pnpm astro add @astrojs/tailwind

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

    Terminal window
    pnpm add @astrojs/starlight-tailwind

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

    src/styles/tailwind.css
    @tailwind base;
    @tailwind components;
    @tailwind utilities;

  4. astro.config.mjsを更新します

    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,
        }),
    ],
    });

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

    tailwind.config.mjs
    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の公式サイトを参照してください。

tailwind.config.mjs
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()],
};

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

Image from Gyazo

カスタムテーマの作成

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

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

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

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

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

Starlightのi18n機能

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

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

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

i18nの設定方法

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

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

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

    astro.config.mjs
    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: '日本語',
                    },
                    // 他の言語を追加
                },
            }),
        ],
    });

  2. src/content/docs/に各言語のディレクトリを作成します：

    • ディレクトリsrc/
      • ディレクトリcontent/
        • …
      • ディレクトリdocs/
        • ディレクトリen/
          • …
        • ディレクトリja/
          • …
        • … 他の言語ディレクトリ

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

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

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

    astro.config.mjs
    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フォントを利用する

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

Fontsourceフォントの設定

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

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

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

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

    例えば、Noto Sans JPを使用する場合：

    Terminal window
    pnpm add @fontsource-variable/noto-sans-jp

  2. astro.config.mjsの設定

    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-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ファイルでフォントを設定します：

tailwind.config.mjs
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()],
};

TerraformでCloudflare PagesにAstroをデプロイ(GitHub連携)

Terraform（またはOpenTofu）を使用してCloudflare PagesにAstroプロジェクトをGithub連携でデプロイしたので備忘録として残します。

Terraformを使用することで、インフラをコードとして管理し、デプロイプロセスを自動化できます。

前提条件

  • Terraform（またはOpenTofu）がインストールされていること
  • Cloudflareアカウントとアクセストークン
  • GitHubアカウントとリポジトリにプッシュされたAstroプロジェクト

また、今回は個人開発前提なので下記の運用とします。

  • Astroプロジェクトのgitレポジトリにそのままtfファイルを追加(モノレポ)
  • tfstateファイルはローカルでのみ管理

手順

Terraformプロジェクトの設定

まず、Terraformの設定ファイルを作成します。

Terminal window
touch main.tf variables.tf

variables.tfファイルの作成

variables.tfファイルに必要な変数を定義します。

variables.tf
variable "cloudflare_api_token" {
  description = "Cloudflare API Token"
  type        = string
}


variable "cloudflare_account_id" {
  description = "Cloudflare Account ID"
  type        = string
}


variable "production_branch" {
  description = "Production branch name"
  type        = string
  default     = "main"
}


variable "github_repo_name" {
  description = "Name of GitHub repository"
  type        = string
}


variable "github_owner" {
  description = "Owner of GitHub repository"
  type        = string
}

main.tfファイルの作成

main.tfファイルにCloudflare Pagesプロジェクトのリソースを追加します。

main.tf
terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 3.0"
    }
  }
}


provider "cloudflare" {
  api_token = var.cloudflare_api_token
}


resource "cloudflare_pages_project" "astro_project" {
  account_id        = var.cloudflare_account_id
  name              = var.github_repo_name
  production_branch = var.production_branch


  source {
    type = "github"
    config {
      owner                         = var.github_owner
      repo_name                     = var.github_repo_name
      production_branch             = "main"
      pr_comments_enabled           = true
      deployments_enabled           = true
      production_deployment_enabled = true
    }
  }


  build_config {
    build_command   = "npm run build"
    destination_dir = "dist"
    root_dir        = "/"
  }


  deployment_configs {
    preview {
      environment_variables = {
        NODE_VERSION = "20.9.0"
      }
    }
    production {
      environment_variables = {
        NODE_VERSION = "20.9.0"
      }
    }
  }
}


pnpmを使う場合は、`build_command`を`npm i -g pnpm && pnpm i && pnpm build`に変更してください。

tfvarsファイルの作成(オプション)

terraform.tfvarsファイルにCloudflare API TokenとアカウントIDを追加します。

これを書いておくと、terraform applyコマンドを実行する際に変数の値を入力する必要がなくなります。

terraform.tfvars
cloudflare_api_token = "自分のCloudflare API Token"
cloudflare_account_id = "自分のCloudflare Account ID"
github_repo_name = "Astroプロジェクトのリポジトリ名"
github_owner = "Astroプロジェクトのリポジェクトのオーナー名"

branchはデフォルトでmainになっていますが、変更したい場合はterraform.tfvarsに追加してください。

カスタムドメインの設定（オプション）

カスタムドメインを設定する場合は、以下のリソースをmain.tfに追加します。

main.tf
resource "cloudflare_pages_domain" "custom_domain" {
  account_id   = var.cloudflare_account_id
  project_name = cloudflare_pages_project.astro_project.name
  domain       = "your-custom-domain.com"
}

Terraformの初期化と適用

以下のコマンドを実行して、Terraformプロジェクトを初期化し、リソースを作成します。

TerraformはライセンスがBSL1.1であるため、オープンソースの代替としてOpenTofuを使用することもできます。

Terminal window
terraform init
terraform apply -auto-approve

変数の値を入力するよう求められたら、適切な値を入力します。(terraform.tfvarsを作成している場合は不要)

デプロイの確認

Terraformの適用が完了したら、Cloudflareダッシュボードで新しく作成されたPagesプロジェクトを確認できます。

GitHubリポジトリへの変更がプッシュされると、自動的にビルドとデプロイが開始されます。

AstroのStarlightテンプレートにブログを追加する

Starlightはドキュメントサイト用のテンプレートですが、プラグインを追加することでブログを導入することもできます。

この記事では、AstroのStarlightテンプレートにブログ機能を追加する方法を紹介します。

Starlightプロジェクトの作成

Starlightでプロジェクトを作成していない方は、下記の記事を参考に作成してください。

Starlightのプロジェクトを作成する

ブログを導入する

ブログを導入するには、以下の手順に従ってください。

  1. 以下のコマンドをプロジェクトのルートで実行して、ブログを追加します。

    Terminal window
    pnpm add starlight-blog

  2. プラグインを追加するために、設定ファイルastro.config.mjsに以下のコードを追加します。

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightBlog from 'starlight-blog'
    

    export default defineConfig({
    integrations: [
        starlight({
        plugins: [starlightBlog()],
        title: 'My Docs',
        }),
    ],
    })

  3. 右上にBlogのリンクが追加されているのでクリックしてブログを確認します。

    Image from Gyazo

  4. ブログページが表示されます。

    Image from Gyazo

ブログ記事を追加する

ブログページができたので、実際にブログ記事を追加してみましょう。

  1. まず、ブログ記事を追加するためのスキーマを作成します。src/content.config.tsに以下のコードを追加します。

    src/content.config.ts
    import { defineCollection } from 'astro:content';
    import { docsLoader } from '@astrojs/starlight/loaders';
    import { docsSchema } from '@astrojs/starlight/schema';
    import { blogSchema } from 'starlight-blog/schema';
    

    export const collections = {
    docs: defineCollection({
        loader: docsLoader(),
        schema: docsSchema(
            {
                extend: (context) => blogSchema(context)
            }
        )
    }),
    };

  2. ブログ記事を追加するための、src/content/docs/blog/ディレクトリを作成します。

    bash/zsh
    mkdir -p src/content/docs/blog

  3. ブログ記事を追加するには、src/content/docs/blog/ディレクトリにmdまたはmdxファイルを作成します。

    md
    touch src/content/docs/blog/test.mdx

  4. 以下のコードをsrc/content/docs/blog/test.mdxに追加します。

    src/content/docs/blog/test.mdx
    ---
    title: Test
    date: 2025-03-10
    ---
    

    ## Test
    

    Test

    titleとdateは必須です。

  5. コマンドを実行して、ブログを確認します。

    Terminal window
    pnpm dev

  6. localhost:4321/blog/を表示し、ブログ記事が表示されていることを確認します。

    Image from Gyazo

タグを追加する

ブログ記事にタグを追加することができます。

markdownファイルにtagsを追加することで、タグを追加できます。

src/content/docs/blog/test.mdx
---
title: test
date: 2025-03-10
tags: [test, astro]
---


## test


Test

これで、testとastroのタグが追加されます。

日本語対応する

BlogプラグインのデフォルトUIに日本語が未対応なので、日本語対応を行います。

  1. src/content.config.tsに以下のコードを追加します。

    src/content.config.ts
    import { defineCollection } from 'astro:content';
    import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders';
    import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
    import { blogSchema } from 'starlight-blog/schema';
    

    export const collections = {
        docs: defineCollection({
            loader: docsLoader(),
            schema: docsSchema(
                {
                    extend: (context) => blogSchema(context)
                }
            )
        }),
        i18n: defineCollection({
            loader: i18nLoader(),
            schema: i18nSchema()
        }),
    };

  2. src/content/i18n/ディレクトリを作成します。

    bash/zsh
    mkdir -p src/content/i18n

  3. src/content/i18n/ディレクトリにja.jsonファイルを作成します。

    ja.json
    touch src/content/i18n/ja.json

  4. 以下のコードをsrc/content/i18n/ja.jsonに追加します。

    src/content/i18n/ja.json
    {
        "starlightBlog.authors.count_one": "{{author}}の投稿: {{count}} 件",
        "starlightBlog.authors.count_other": "{{author}}の投稿: {{count}} 件",
        "starlightBlog.pagination.prev": "新しい投稿",
        "starlightBlog.pagination.next": "古い投稿",
        "starlightBlog.post.lastUpdate": " - 最終更新日: {{date}}",
        "starlightBlog.post.draft": "下書き",
        "starlightBlog.post.featured": "おすすめ",
        "starlightBlog.post.tags": "タグ:",
        "starlightBlog.sidebar.all": "すべての投稿",
        "starlightBlog.sidebar.featured": "おすすめの投稿",
        "starlightBlog.sidebar.recent": "最新の投稿",
        "starlightBlog.sidebar.tags": "タグ",
        "starlightBlog.sidebar.authors": "著者",
        "starlightBlog.sidebar.rss": "RSS",
        "starlightBlog.tags.count_one": "“{{tag}}” の投稿: {{count}} 件",
        "starlightBlog.tags.count_other": "{{tag}}” の投稿: {{count}} 件"
    }

  5. コマンドを実行して、ブログを確認します。

    Terminal window
    pnpm dev

  6. localhost:4321/blog/を表示し、UIが日本語になっていることを確認します。

    Image from Gyazo

これで最低限日本語対応したブログを運営できるかと思います。

細かいカスタマイズは、Starlightのドキュメントを参考にしてください。

参考

AstroのテンプレートStarlightで簡単にドキュメントサイトを作る

Astroでドキュメントサイトを作るのにStarlightというテンプレートを使ってみたので、備忘録として残します。

サクッと日本語のドキュメントサイトをMarkdownで作りたい場合は、Starlightがおすすめです。

Astro/Starlightのインストール

まずは、Starlightを使ってプロジェクトを作成します。

  1. 以下のコマンドを実行して、Starlightを使ったプロジェクトを作成します(プロジェクト名は適宜お好きなものを入れてください)。

    Terminal window
    pnpm create astro プロジェクト名 --yes --template starlight

  2. 以下のようなメッセージが表示されたら、プロジェクトの作成が完了です。

    Terminal window
      ✔  Project initialized!
         ■ Template copied
         ■ Dependencies installed
         ■ Git initialized
    

    next   Liftoff confirmed. Explore your project!
    

            Enter your project directory using cd ./プロジェクト名
            Run pnpm dev to start the dev server. CTRL+C to stop.
            Add frameworks like react or tailwind using astro add.
    

            Stuck? Join us at https://astro.build/chat
    

    ╭─────╮  Houston:
    │ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
    ╰─────╯

  3. インストールが完了したら、プロジェクトディレクトリに移動します(適宜自分が作成したプロジェクト名に修正してください)。

    Terminal window
    cd プロジェクト名

  4. ローカルサーバーを起動します。

    Terminal window
    pnpm dev

  5. ブラウザで http://localhost:4321 にアクセスして、トップページを確認します。

    Image from Gyazo

  6. 「Example Guide」ボタンをクリックすると、ドキュメントページに遷移します。

    Image from Gyazo

これで、AstroのテンプレートStarlightを使ってドキュメントサイトを作成することができました。

ドキュメントを追加する

サイトは作成できましたが、ドキュメントがまだありません。

ドキュメントを追加するには、src/content/docs/ディレクトリにmdまたはmdxファイルを作成します。

  1. プロジェクトのディレクトリで以下のコマンドを実行して、ドキュメントを追加します。

    Terminal window
    touch src/content/docs/test.md

  2. 作成したmdxファイルに以下の内容を記述します。

    src/content/docs/test.mdx
    ---
    title: test
    ---
    # test

  3. ローカルサーバーを起動します。

    Terminal window
    pnpm dev

  4. ブラウザでhttp://localhost:4321/testにアクセスして、ドキュメントが表示されることを確認します。

    Image from Gyazo

サイドバーにドキュメントを追加する

今のままだと、直接URLを入力しないとドキュメントにアクセスできません。

サイドバーにドキュメントのリンクを追加して、アクセスしやすくします。

  1. src/astro.config.mjsファイルを開いて、以下のようにsidebarを追加します。

    astro.config.mjs
    // @ts-check
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';
    

    // https://astro.build/config
    export default defineConfig({
        integrations: [
            starlight({
                title: 'My Docs',
                social: {
                    github: 'https://github.com/withastro/starlight',
                },
                sidebar: [
                    {
                        label: 'Guides',
                        items: [
                            // Each item here is one entry in the navigation menu.
                            { label: 'Example Guide', slug: 'guides/example' },
                        ],
                    },
                    {
                        label: 'Reference',
                        autogenerate: { directory: 'reference' },
                    },
                    {
                        label: 'Test', link: '/test/'
                    },
                ],
            }),
        ],
    });

  2. ローカルサーバーを再起動します。

    Terminal window
    pnpm dev

  3. ブラウザで http://localhost:4321 にアクセスし、「Example Guide」ボタンをクリックしてサイドバーにドキュメントが追加されていることを確認します。

    Image from Gyazo

これで、サイドバーにドキュメントを追加することができました。

サイドバーにサブメニューを追加する

今のままだとサイドバーにドキュメントのリンクを追加することはできますが、ドキュメントサイトによくある分類されたサブメニューを追加することはできません。

既にサイドバーでサブメニューが使われているGuidesとReferenceを見てみましょう。

直接記述して生成する

まずは、直接記述してサブメニューを生成します。

Guidesのサブメニューをみてみましょう。

astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
                {
                    label: 'Test', link: '/test/'
                },
      ],
    }),
  ],
});

sidebarの中にGuidesというラベルがあり、その中にitemsという配列があります。itemsの中には、サブメニューの項目が入っています。

Guidesのサブメニューに新しい項目を追加するには、itemsの中に新しい項目を追加します。

実際にtest.mdのリンクを追加してみましょう。

astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
            { label: 'Test', slug: 'test' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
                {
                    label: 'Test', link: '/test/'
                },
      ],
    }),
  ],
});

slugには、src/content/docs/ディレクトリに作成したmdまたはmdxファイルの名前を指定します。(今回はtest.mdxなので、slugにはtestを指定します)

サーバーを起動して、サイドバーにサブメニューが追加されていることを確認します。

Image from Gyazo

ディレクトリ構造から生成する

毎回astro.config.mjsに直接記述するのは面倒なので、ディレクトリ構造から自動生成する方法を紹介します。

Referenceのサブメニューをみてみましょう。

astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
            { label: 'Test', slug: 'test' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
                {
                    label: 'Test', link: '/test/'
                },
      ],
    }),
  ],
});

Referenceのサブメニューはautogenerateというオブジェクトを使って自動生成されています。

autogenerateのdirectoryには、ドキュメントを配置するディレクトリを指定します。

Referenceのサブメニューを追加するには、src/content/reference/ディレクトリにmdまたはmdxファイルを作成します。

実際に先ほどのtest.mdxをコピーしてsrc/content/reference/test.mdxを作成してみましょう。

Terminal window
cp src/content/docs/test.mdx src/content/docs/reference/test.mdx

サーバーを起動して、サイドバーにサブメニューが追加されていることを確認します。

Image from Gyazo

これで、サイドバーにサブメニューを追加することができました。

違う分類を追加したい場合は、同じようにディレクトリを作成しsidebarに追加すれば良いです。

一般的な用途では、ディレクトリ構造から自動生成する方法を使うと便利ですが、同じmdxを使いまわしたい場合は直接記述する方法を使うと良いかもしれません。

サイトタイトルを変更する

デフォルトでは、サイトのタイトルが「My Docs」になっています。

サイトタイトルを変更するには、src/astro.config.mjsファイルを開いて、titleを変更します。

astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'Test Docs',
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
            { label: 'Test', slug: 'test' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
                {
                    label: 'Test', link: '/test/'
                },
      ],
    }),
  ],
});

titleには、サイトのタイトルを指定します。

サーバーを起動して、サイトタイトルが変更されていることを確認します。

Image from Gyazo

トップページをドキュメントにする

簡易的なドキュメントサイトだとトップページがランディングページでなくても良い場合があります。

その場合は、src/content/docs/ディレクトリのindex.mdxファイルを修正します。

具体的には、下記の通り4行目のtemplate: splashを削除します。

src/content/docs/index.mdx
---
title: Welcome to Starlight
description: Get started building your docs site with Starlight.
template: splash
hero:
  tagline: Congrats on setting up a new Starlight project!
  image:
    file: ../../assets/houston.webp
  actions:
    - text: Example Guide
      link: /guides/example/
      icon: right-arrow
    - text: Read the Starlight docs
      link: https://starlight.astro.build
      icon: external
      variant: minimal
---


import { Card, CardGrid } from '@astrojs/starlight/components';


## Next steps


<CardGrid stagger>
  <Card title="Update content" icon="pencil">
    Edit `src/content/docs/index.mdx` to see this page change.
  </Card>
  <Card title="Add new content" icon="add-document">
    Add Markdown or MDX files to `src/content/docs` to create new pages.
  </Card>
  <Card title="Configure your site" icon="setting">
    Edit your `sidebar` and other config in `astro.config.mjs`.
  </Card>
  <Card title="Read the docs" icon="open-book">
    Learn more in [the Starlight Docs](https://starlight.astro.build/).
  </Card>
</CardGrid>

Starlightでは、template: splashを指定することでページからサイドバーを消すことができます。

トップページは上記を指定することで、ランディングページとして作成されています。

templeteを削除してデフォルトに戻すことで、トップページをドキュメントにすることができます(defaultはtemplate: docs)。

サーバーを起動して、トップページがドキュメントになっていることを確認します。

Image from Gyazo

これで、トップページをドキュメントにすることができました。

日本語対応する

今のままだと検索バーやダークモードの切り替えなどが英語のままです。

使えはしますが、日本語でドキュメントサイトを作るなら日本語対応すると良いでしょう。

Starlightはデフォルトで日本語にも対応しています。

src/astro.config.mjsファイルを開いて、以下のようにlocalesを追加します。

astro.config.mjs
// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';


// https://astro.build/config
export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
            locales: {
                root: {
                    label: '日本語',
                    lang: 'ja',
                },
            },
      social: {
        github: 'https://github.com/withastro/starlight',
      },
      sidebar: [
        {
          label: 'Guides',
          items: [
            // Each item here is one entry in the navigation menu.
            { label: 'Example Guide', slug: 'guides/example' },
            { label: 'Test', slug: 'test' },
          ],
        },
        {
          label: 'Reference',
          autogenerate: { directory: 'reference' },
        },
                {
                    label: 'Test', link: '/test/'
                },
      ],
    }),
  ],
});

localesの中にrootを設定することで、日本語に対応します。

サーバーを起動して、日本語に対応していることを確認します。

Image from Gyazo

これで、日本語対応することができました。

ここまでで、最低限日本語のドキュメントサイトを作るには十分かと思います。

細かいカスタマイズは、Starlightのドキュメントを参考にしてください。

参考