starlight-blog 📰

Astro integration for Starlight to add a blog to your documentation.

Features

An Astro integration for Starlight to add a blog to your documentation website.

Link to the blog in the header
Post list with pagination
Global and per-post authors
Tags
Custom sidebar with recent posts and tags

Some features are still missing and will be added in the future like internationalization, feeds, reading time, etc.

Installation

Install the Starlight Blog integration using your favorite package manager, e.g. with pnpm:

pnpm add starlight-blog

Update your Astro configuration to include the Starlight Blog integration before the Starlight integration and configure the various component overrides required by the integration:

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

  export default defineConfig({
    // …
    integrations: [
+     starlightBlog(),
      starlight({
+       components: {
+         MarkdownContent: 'starlight-blog/overrides/MarkdownContent.astro',
+         Sidebar: 'starlight-blog/overrides/Sidebar.astro',
+         ThemeSelect: 'starlight-blog/overrides/ThemeSelect.astro',
+       },
        sidebar: [
          {
            label: 'Guides',
            items: [{ label: 'Example Guide', link: '/guides/example/' }],
          },
        ],
        title: 'My Docs',
      }),
    ],
  })

Update the Starlight Content Collections configuration in src/content/config.ts to use a new schema supporting blog posts:

  import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'
  import { defineCollection } from 'astro:content'
+ import { docsAndBlogSchema } from 'starlight-blog/schema'

  export const collections = {
-   docs: defineCollection({ schema: docsSchema() }),
+   docs: defineCollection({ schema: docsAndBlogSchema }),
    i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
  }

Create your first blog post by creating a .md or .mdx file in the src/content/docs/blog/ directory:

---
title: My first blog post
date: 2023-07-24
---

## Hello

Hello world!

Configuration

You can pass the following options to the Starlight Blog integration:

Name	Description	Default
`authors`	A list of global authors. Check the authors section for more informations.	{}
`postCount`	The number of blog posts to display per page in the blog post list.	5
`recentPostCount`	The number of recent blog posts to display in the sidebar.	10
`title`	The title of the blog.	'Blog'

Frontmatter

Individual blog posts can be customized using their frontmatter. A blog post must at least have a title and a date (posts are sorted by descending date) property:

---
title: Documentation 101
date: 2023-07-24
---

Let's learn how to write documentation!

Name	Description	Required
`authors`	The author(s) of the blog post. Check the authors section for more informations.
`date`	The date of the blog post which must be a valid YAML timestamp.	✅
`excerpt`	The excerpt of the blog post used in the blog post list and tags pages. If not provided, the entire blog post content will be rendered.
`tags`	A list of tags associated with the blog post.

Authors

Authors can be defined in a blog post using the authors frontmatter property and must at least have a name property:

authors:
  name: HiDeoo
  title: Starlight Aficionado
  picture: https://avatars.githubusercontent.com/u/494699
  url: https://hideoo.dev

Multiple authors can be defined using an array:

authors:
  - name: HiDeoo
    title: Starlight Aficionado
    picture: https://avatars.githubusercontent.com/u/494699
    url: https://hideoo.dev
  - name: Ghost
    picture: https://avatars.githubusercontent.com/u/10137
    url: https://github.com/ghost

Regular authors can also be defined globally in the Starlight Blog integration configuration:

starlightBlog({
  authors: {
    hideoo: {
      name: 'HiDeoo',
      title: 'Starlight Aficionado',
      picture: '/hideoo.png', // Images in the `public` directory are supported.
      url: 'https://hideoo.dev',
    },
  },
})

When a blog post frontmatter does not define an author, the global authors from the configuration will be used instead.

A blog post frontmatter can also reference a global author using the key of the author in the configuration:

authors:
  - hideoo # Will use the author defined in the configuration with the `hideoo` key.
  - name: Ghost
    picture: https://avatars.githubusercontent.com/u/10137
    url: https://github.com/ghost

License

See LICENSE for more information.

Fryuni / starlight-blog