Skip to content
Clameyes
Blog

Astro

9 posts with the tag “Astro”

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

参考リンク

Implementing Comment Functionality (Giscus) in Astro Starlight

I’ve implemented a comment feature (Giscus) using GitHub Discussions in Astro’s documentation template Starlight, so I’m leaving this as a record for future reference.

What is Giscus?

Giscus is a commenting system that utilizes GitHub Discussions.

It’s lightweight and uses GitHub authentication, making it excellent for spam prevention.

Prerequisites

  • An Astro Starlight website is set up
  • You have a GitHub account
  • You have a repository with GitHub Discussions enabled

Installation Steps

  1. Install starlight-giscus

    First, install the starlight-giscus plugin. Run the following command in your terminal:

    Terminal window
    pnpm add starlight-giscus

  2. Configure the Giscus app

    Set up Giscus for your repository on the Giscus official site.

    Enter the required information and generate the script code, then copy it.

  3. Update the Astro configuration file

    Open the astro.config.mjs file and add the following configuration:

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

    Replace the values for repo, repoId, category, and categoryId with those generated in your Giscus configuration.

    These four are required fields, but there are other customization options available. Details will be discussed later.

Customization Options

The starlight-giscus plugin has the following customization options:

  • mapping (string): How to map pages to discussions (what the discussion title will be)
    • pathname (default): Page’s pathname
    • URL: Page’s URL
    • <title>: Page’s title
    • og:title: Page’s og:title
  • reactions (boolean): Enable/disable reactions feature
  • inputPosition (string): Position of the reply form
    • bottom (default): Below comments
    • top: Above comments
  • theme (string): Theme for the comment section
  • lazy (boolean): Enable/disable lazy loading

You can use these options to customize the comment functionality to suit your site.

Disabling Comments on Specific Pages

By default, comments will appear on pages where they might not be necessary, such as the top page, as shown below.

Image from Gyazo

If you have pages where you don’t want comments to appear, you can control this using frontmatter.

Configuration Steps

  1. Extend the schema in the src/content.config.ts file

    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. Add giscus: false to the frontmatter of pages where you want to disable comments.

    ---
    title: Page without comments
    giscus: false
    ---

If Using the starlight-blog Plugin

If you’re using the starlight-blog plugin, call blogSchema(context) within the extend function, then add giscus.

Also, set the default to false if you want to disable giscus on blog pages and tag pages.

Configuration Steps

  1. Extend the schema in the src/content.config.ts file

    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. Add giscus: true to the frontmatter of pages where you want to enable comments.

    ---
    title: Page with comments
    date: 2025-03-17
    giscus: true
    ---

Using Tailwind CSS with Astro Starlight

I tried using Tailwind CSS with Astro’s documentation template Starlight, so here’s a memo for future reference.

Adding Tailwind CSS

We’ll add Tailwind CSS to an existing Starlight project. (For new projects, see here)

  1. Add Astro’s Tailwind integration:

    Terminal window
    pnpm astro add @astrojs/tailwind

  2. Install Starlight’s Tailwind plugin:

    Terminal window
    pnpm add @astrojs/starlight-tailwind

  3. Create a CSS file for Tailwind’s base styles (e.g., src/styles/tailwind.css):

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

  4. Update 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: 'Documentation using Tailwind',
        customCss: [
            './src/styles/tailwind.css',
        ],
        }),
        tailwind({
        applyBaseStyles: false,
        }),
    ],
    });

  5. Add Starlight’s Tailwind plugin to tailwind.config.mjs:

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

Styling Starlight using Tailwind

Starlight uses Tailwind’s theme configuration values in its UI.

As an example, here’s how to change the accent color used for links and other elements:

colors.accent: Used for links and highlighting the current item

We’ll use Tailwind’s color settings for this example.

To check colors, refer to the Tailwind CSS official website.

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

When executed, the colors will change as follows:

Image from Gyazo

Creating a Custom Theme

Starlight’s color themes can be controlled by overriding custom properties.

Starlight provides a theme color editor.

You can access the theme color editor through the link below:

Implementing Multilingual Support in Astro Starlight with i18n Functionality

I’ve implemented multilingual support using Astro’s documentation template Starlight, so I’m leaving this as a record for future reference.

Starlight’s i18n Features

Starlight has built-in internationalization (i18n) features, including:

  • Multilingual routing
  • Fallback content
  • Full support for right-to-left (RTL) languages

These features allow for efficient construction of multilingual sites.

How to Configure i18n

  1. Specify the supported languages in the astro.config.mjs file.

    Also set the default language (for languages not included in the locales).

    In my case, I supported English (en) and Japanese (ja), with English set as the default language.

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

    export default defineConfig({
        integrations: [
            starlight({
                title: 'My Docs',
                defaultLocale: 'en',
                locales: {
                    en: {
                        label: 'English',
                    },
                    ja: {
                        label: '日本語',
                    },
                    // Add other languages
                },
            }),
        ],
    });

  2. Create directories for each language in src/content/docs/:

    • Directorysrc/
      • Directorycontent/
        • …
      • Directorydocs/
        • Directoryen/
          • …
        • Directoryja/
          • …
        • … Other language directories

  3. Place corresponding content files (articles) in each language directory.

    Using the same file name for the same page allows you to link pages across languages.

    If you want to serve a specific language without prefixing the path, you can set a root locale.

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

    In this case, place Japanese content directly under src/content/docs/.

    • Directorysrc/
      • Directorycontent/
        • …
      • Directorydocs/
        • index.md (Japanese index.md)
        • Directoryen/
          • index.md

Fallback Content

For untranslated pages, Starlight automatically displays content in the default language and notifies that it’s untranslated.

This allows for gradual translation of content.

Translating the UI

You can also translate Starlight’s default UI strings. Create JSON files for each language in src/content/i18n/ and add translations.

{
  "search.label": "Search",
  "tableOfContents.onThisPage": "On this page",
  // Other translation keys
}

For more details, refer to the Starlight documentation.

Using Web Fonts with Astro Starlight

I tried using web fonts with Astro’s documentation template Starlight, so here’s a memo for future reference.

Setting up Fontsource Fonts

There are several ways to use web fonts with Starlight, but here I’ll introduce the method using Fontsource.

Fontsource is a package that allows you to easily select and install fonts from font catalogs like Google Fonts and Adobe Fonts.

  1. Installing the font package

    Install your preferred font package from the Fontsource page.

    For example, if you want to use Geist:

    Terminal window
    pnpm add @fontsource-variable/geist

  2. Configuring astro.config.mjs

    Add the Fontsource CSS file to the customCss array in your astro.config.mjs file:

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

    export default defineConfig({
    integrations: [
        starlight({
        title: 'Documentation with Custom Font',
        customCss: [
            '@fontsource-variable/geist',
        ],
        }),
    ],
    });

Applying the Font

To apply the configured font to your site, specify the font name in a custom CSS file.

Applying to the entire site

:root {
  --sl-font: 'Geist Variable', serif;
}

Applying to specific elements only

main {
  font-family: 'Geist Variable', serif;
}

Applying with Tailwind CSS

Set up the font in your tailwind.config.js file:

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: ['Geist Variable'],
      },
    },
  },
  plugins: [starlightPlugin()],
};

Deploy Astro to Cloudflare Pages with Terraform (GitHub Integration)

I deployed an Astro project to Cloudflare Pages using Terraform (or OpenTofu) with GitHub integration, so I’m leaving this as a memo.

By using Terraform, you can manage infrastructure as code and automate the deployment process.

Prerequisites

  • Terraform (or OpenTofu) installed
  • Cloudflare account and access token
  • GitHub account and Astro project pushed to a repository

Also, assuming this is for personal development, we’ll use the following approach:

  • Add tf files directly to the Astro project’s git repository (monorepo)
  • Manage tfstate files locally only

Steps

Setting up the Terraform project

First, create the Terraform configuration files.

Terminal window
touch main.tf variables.tf

Creating the variables.tf file

Define the necessary variables in the variables.tf file.

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
}

Creating the main.tf file

Add the Cloudflare Pages project resource to the main.tf file.

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"
      }
    }
  }
}


If using pnpm, change the `build_command` to `npm i -g pnpm && pnpm i && pnpm build`.

Creating the tfvars file (Optional)

Add your Cloudflare API Token and Account ID to the terraform.tfvars file.

By doing this, you won’t need to input variable values when running the terraform apply command.

terraform.tfvars
cloudflare_api_token = "Your Cloudflare API Token"
cloudflare_account_id = "Your Cloudflare Account ID"
github_repo_name = "Your Astro project repository name"
github_owner = "Owner of your Astro project repository"

The branch is set to main by default, but if you want to change it, add it to terraform.tfvars.

Setting up a custom domain (Optional)

To set up a custom domain, add the following resource to 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"
}

Initializing and applying Terraform

Run the following commands to initialize the Terraform project and create resources.

As Terraform is licensed under BSL1.1, you can also use OpenTofu as an open-source alternative.

Terminal window
terraform init
terraform apply -auto-approve

If prompted for variable values, enter the appropriate values. (Not necessary if you’ve created terraform.tfvars)

Confirming the deployment

After Terraform has been applied, you can check the newly created Pages project in your Cloudflare dashboard.

When changes are pushed to the GitHub repository, the build and deployment will start automatically.

Adding a Blog to Astro's Starlight Template

While Starlight is a template for documentation sites, you can also introduce a blog by adding plugins.

This article will introduce how to add blog functionality to Astro’s Starlight template.

Creating a Starlight Project

If you haven’t created a Starlight project yet, please refer to the following article to create one:

Create a Starlight Project

Introducing the Blog

To introduce the blog, follow these steps:

  1. Run the following command in the project root to add the blog:

    Terminal window
    pnpm add starlight-blog

  2. To add the plugin, add the following code to the configuration file 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. Click on the Blog link added to the top right to check the blog.

    Image from Gyazo

  4. The blog page will be displayed.

    Image from Gyazo

Adding Blog Posts

Now that we have a blog page, let’s actually add some blog posts.

  1. First, create a schema to add blog posts. Add the following code to 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. Create a src/content/docs/blog/ directory to add blog posts.

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

  3. To add a blog post, create an md or mdx file in the src/content/docs/blog/ directory.

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

  4. Add the following code to src/content/docs/blog/test.mdx:

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

    ## Test
    

    Test

    Title and date are required.

  5. Run the command to check the blog:

    Terminal window
    pnpm dev

  6. Display localhost:4321/blog/ and confirm that the blog post is displayed.

    Image from Gyazo

Adding Tags

You can add tags to blog posts.

You can add tags by adding tags to the markdown file.

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


## test


Test

This will add the tags test and astro.

Japanese Localization

As the default UI of the Blog plugin doesn’t support Japanese, we’ll localize it to Japanese.

You can also localize it to other languages by following the same steps.

  1. Add the following code to 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. Create a src/content/i18n/ directory.

    bash/zsh
    mkdir -p src/content/i18n

  3. Create a ja.json file in the src/content/i18n/ directory.

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

  4. Add the following code to 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. Run the command to check the blog:

    Terminal window
    pnpm dev

  6. Display localhost:4321/blog/ and confirm that the UI is in Japanese.

    Image from Gyazo

This should allow you to run a minimally Japanese-localized blog.

For detailed customization, please refer to the Starlight documentation.

References

Creating a Documentation Site Easily with Astro's Starlight Template

I tried using a template called Starlight to create a documentation site with Astro, so I’m leaving this as a memo.

If you want to quickly create a Japanese documentation site using Markdown, Starlight is recommended.

Installing Astro/Starlight

First, let’s create a project using Starlight.

  1. Run the following command to create a project using Starlight (replace the project name with one of your choice).

    Terminal window
    pnpm create astro project-name --yes --template starlight

  2. When you see a message like the following, the project creation is complete.

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

    next   Liftoff confirmed. Explore your project!
    

            Enter your project directory using cd ./project-name
            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. After installation is complete, move to the project directory (modify this to the project name you created).

    Terminal window
    cd project-name

  4. Start the local server.

    Terminal window
    pnpm dev

  5. Access http://localhost:4321 in your browser to check the top page.

    Image from Gyazo

  6. Click the “Example Guide” button to navigate to the documentation page.

    Image from Gyazo

With this, you have successfully created a documentation site using Astro’s Starlight template.

Adding Documents

You’ve created the site, but there are no documents yet.

To add documents, create md or mdx files in the src/content/docs/ directory.

  1. Run the following command in your project directory to add a document:

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

  2. Write the following content in the created mdx file:

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

  3. Start the local server:

    Terminal window
    pnpm dev

  4. Access http://localhost:4321/test in your browser to confirm that the document is displayed.

    Image from Gyazo

Adding Documents to the Sidebar

As it is now, you can’t access the document unless you directly enter the URL.

Let’s add a link to the document in the sidebar to make it easier to access.

  1. Open the src/astro.config.mjs file and add sidebar as follows:

    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. Restart the local server:

    Terminal window
    pnpm dev

  3. Access http://localhost:4321 in your browser, click the “Example Guide” button, and confirm that the document has been added to the sidebar.

    Image from Gyazo

Now you’ve successfully added documents to the sidebar.

Adding Submenus to the Sidebar

As it is now, you can add document links to the sidebar, but you can’t add classified submenus that are common in document sites.

Let’s look at the Guides and Reference that are already using submenus in the sidebar.

Generating by Direct Description

First, let’s generate submenus by direct description.

Let’s look at the Guides submenu.

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

In the sidebar, there’s a label called Guides, and within it, there’s an array called items. The items array contains the submenu items.

To add a new item to the Guides submenu, add a new item to the items array.

Let’s actually add a link to 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/'
                },
      ],
    }),
  ],
});

For the slug, specify the name of the md or mdx file you created in the src/content/docs/ directory. (In this case, it’s test.mdx, so we specify ‘test’ for the slug)

Start the server and confirm that the submenu has been added to the sidebar.

Image from Gyazo

Generating from Directory Structure

It’s troublesome to directly write in astro.config.mjs every time, so let’s introduce a method to automatically generate from the directory structure.

Let’s look at the Reference submenu.

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

The Reference submenu is automatically generated using an object called autogenerate.

In the directory of autogenerate, specify the directory where you want to place the documents.

To add a submenu to Reference, create md or mdx files in the src/content/reference/ directory.

Let’s actually copy the previous test.mdx and create src/content/reference/test.mdx:

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

Start the server and confirm that the submenu has been added to the sidebar.

Image from Gyazo

Now you’ve successfully added submenus to the sidebar.

If you want to add a different classification, you can simply create a directory in the same way and add it to the sidebar.

For general use, the method of automatically generating from the directory structure is convenient, but if you want to reuse the same mdx, it might be good to use the direct description method.

Changing the Site Title

By default, the site title is set to “My Docs”.

To change the site title, open the src/astro.config.mjs file and change the 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/'
                },
      ],
    }),
  ],
});

Specify the site title in the title.

Start the server and confirm that the site title has been changed.

Image from Gyazo

Making the Top Page a Document

For simple document sites, it might be fine if the top page isn’t a landing page.

In that case, modify the index.mdx file in the src/content/docs/ directory.

Specifically, delete template: splash on line 4 as shown below:

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>

In Starlight, specifying template: splash allows you to remove the sidebar from the page.

The top page is created as a landing page by specifying the above.

By removing the template and returning to the default, you can make the top page a document (the default is template: docs).

Start the server and confirm that the top page has become a document.

Image from Gyazo

Now you’ve successfully made the top page a document.

At this point, I think it’s sufficient to create a basic document site.

Supporting Japanese(or other languages)

As it is now, the search bar, dark mode toggle, etc. are still in English.

It’s usable, but if you’re creating a document site in Japanese, it would be good to support Japanese (or other languages).

Starlight supports Japanese by default.

Open the src/astro.config.mjs file and add locales as follows:

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

By setting root in locales, you support Japanese.

Start the server and confirm that it now supports Japanese.

Image from Gyazo

Now you’ve successfully supported Japanese.

At this point, I think it’s sufficient to create a basic Japanese(or other langueges) document site.

For detailed customization, please refer to the Starlight documentation.

References