Starlight

6 posts with the tag “Starlight”

Implementing Comment Functionality (Giscus) in Astro Starlight

Mar 17, 2025

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:

   pnpm

   pnpm add starlight-giscus

   npm

   npm install starlight-giscus

   yarn

   yarn 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
  • preferred_color_scheme (default): Matches user’s OS theme
  • For others, refer to Starlight-Giscus documentation
• 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.

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

Tags:

• Astro
• Starlight

Using Tailwind CSS with Astro Starlight

Mar 16, 2025

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:

   pnpm

   pnpm astro add @astrojs/tailwind

   npm

   npx astro add @astrojs/tailwind

   Yarn

   yarn astro add @astrojs/tailwind

   
   

   Caution

   Currently, Astro installs Tailwind CSS v4 by default. Since Starlight is not yet compatible with v4, we’re installing v3 as shown above.

2. Install Starlight’s Tailwind plugin:

   pnpm

   pnpm add @astrojs/starlight-tailwind

   npm

   npm install @astrojs/starlight-tailwind

   Yarn

   yarn 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:

Before

After

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:

• Starlight Theme Color Editor

Tags:

• Astro
• Starlight
• Tailwind

Implementing Multilingual Support in Astro Starlight with i18n Functionality

Mar 16, 2025

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.

Tags:

• astro
• starlight

Using Web Fonts with Astro Starlight

Mar 16, 2025

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:

   pnpm

   pnpm add @fontsource-variable/geist

   npm

   npm install @fontsource-variable/geist

   Yarn

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

Tags:

• Astro
• Starlight

Adding a Blog to Astro's Starlight Template

Mar 10, 2025

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:

   pnpm

   pnpm add starlight-blog

   npm

   npm i starlight-blog

   yarn

   yarn 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.

   

4. The blog page will be displayed.

   

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

   bash/zsh

   mkdir -p src/content/docs/blog

   PowerShell

   PowerShell

   New-Item -Path src/content/docs/blog -ItemType Directory

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

   bash/zsh

   md

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

   PowerShell

   mdx

   NewItem 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:

   pnpm

   pnpm dev

   npm

   npm run dev

   yarn

   yarn dev

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

   

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

   bash/zsh

   mkdir -p src/content/i18n

   PowerShell

   PowerShell

   New-Item -Path src/content/i18n -ItemType Directory

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

   bash/zsh

   ja.json

   touch src/content/i18n/ja.json

   PowerShell

   ja.json

   NewItem 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:

   pnpm

   pnpm dev

   npm

   npm run dev

   yarn

   yarn dev

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

   

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

For detailed customization, please refer to the Starlight documentation.

References

• https://github.com/HiDeoo/starlight-blog
• https://starlight-blog-docs.vercel.app/

Tags:

• Astro
• Starlight

Creating a Documentation Site Easily with Astro's Starlight Template

Mar 10, 2025

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).

   pnpm

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

   npm

   npm create astro@latest project-name --yes --template starlight

   yarn

   yarn create astro project-name --yes --template starlight

   
   

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

     ✔  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).

   cd project-name

4. Start the local server.

   pnpm

   pnpm dev

   npm

   npm run dev

   yarn

   yarn dev

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

   

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

   

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:

   bash/zsh

   touch src/content/docs/test.md

   PowerShell

   New-File src/content/docs/test.mdx

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

   src/content/docs/test.mdx

   ---
   title: test
   ---
   # test

3. Start the local server:

   pnpm

   pnpm dev

   npm

   npm run dev

   yarn

   yarn dev

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

   

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:

   pnpm

   pnpm dev

   npm

   npm run dev

   yarn

   yarn 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.

   

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.

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:

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.

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.

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.

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.

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

• https://starlight-blog-docs.vercel.app/getting-started/

Tags:

• Astro
• Starlight