Changesets

The Starlight Changelogs plugin uses Astro’s content collections, which are configured in the src/content.config.ts file. The provided changelogsLoader() loader can be used to load one or more changelog files from different providers, including Changesets.

Both the @changesets/changelog-github and @changesets/changelog-git changelog formats are supported by the plugin.

Changelog files generated by Changesets can be loaded by using the provider: 'changeset' option.

src/content.config.ts

import { docsLoader } from '@astrojs/starlight/loaders'
import { docsSchema } from '@astrojs/starlight/schema'
import { defineCollection } from 'astro:content'
import { changelogsLoader } from 'starlight-changelogs/loader'

export const collections = {
  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
  changelogs: defineCollection({
    loader: changelogsLoader([
      {
        provider: 'changeset',
        // Changelog options go here.
      },
    ]),
  }),
}

Provider configuration

The Changesets provider accepts the following configuration options:

provider

Required
Type: 'changeset'

Defines the provider to use for loading the changelog file. This should always be set to 'changeset' for the Changesets provider.

changelogsLoader([
  {
    provider: 'changeset',
  },
])

base

Required
Type: string

Set the base path to use for this changelog.

For example, setting this option to changelog will result in the changelog version list being available at /changelog/ and a version entry at /changelog/versions/0.1.0/.

changelogsLoader([
  {
    base: 'changelog',
  },
])

changelog

Required
Type: string

Defines the path or URL of the changelog file generated by Changeset to load.

When using a path, it should be relative to the root of the Starlight project.

changelogsLoader([
  {
    changelog: '../packages/my-packages/CHANGELOG.md',
  },
])

When using a URL, it should point to a raw file that contains the changelog, e.g. a GitHub raw URL.

changelogsLoader([
  {
    changelog:
      'https://raw.githubusercontent.com/HiDeoo/starlight-blog/refs/heads/main/packages/starlight-blog/CHANGELOG.md',
  },
])

title

Type: string | Record<string, string>
Default: 'Changelog'

The title of the changelog.

The value can be a string, or for multilingual sites, an object with values for each different locale.

changelogsLoader([
  {
    title: 'Version History',
  },
])

When using the object form, the keys must be BCP-47 tags (e.g. en, fr, or zh-CN).

changelogsLoader([
  {
    title: {
      en: 'Version History',
      fr: 'Historique des versions',
    },
  },
])

pageSize

Type: number
Default: 10

The number of versions to display per page in the changelog version list.

changelogsLoader([
  {
    pageSize: 20,
  },
])

pagefind

Type: boolean
Default: true

Defines whether the changelog pages should be indexed by Pagefind, Starlight’s default site search provider.

changelogsLoader([
  {
    pagefind: false,
  },
])

process

Type: ({ name }: { name: string }) => string | undefined

Sets an optional function called for every version entry in the changelog which can be used to either modify the version title or filter out certain versions.

The function receives the version title found in the changelog and can use it to return an updated title or undefined to filter out this specific version.

Filtering out versions can be useful for example when using the GitHub provider on a monorepo publishing releases for multiple packages, and only changes for a specific package should be shown in the changelog.

For example, considering a changelog with the following version titles:

• v1.0.1
• v1.0.1-beta.1
• v1.0.0
• v0.1.1
• v0.1.0

The following example will filter out the beta version and strip the v prefix from the version titles:

changelogsLoader([
  {
    process: ({ title }) => {
      // If the version title contains "-beta", filter it out.
      if (title.includes('-beta')) return

      // Otherwise, strip the "v" prefix from the version title,
      // e.g. "v1.0.0" becomes "1.0.0".
      return title.replace(/^v/, '')
    },
  },
])