Skip to content
Clameyes
Blog

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

Tags: