GitHub

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 GitHub releases.

GitHub releases can be loaded by using the provider: 'github' option. Note that the GitHub API can return a maximum of 1000 releases so if you have more versions than this limit, you will need to use another provider.

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: 'github',
        // Changelog options go here.
      },
    ]),
  }),
}

Provider configuration

The GitHub provider accepts the following configuration options:

provider

Required
Type: 'github'

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

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

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

owner

Required
Type: string

The owner of the GitHub repository containing releases to load.

changelogsLoader([
  {
    owner: 'hideoo',
  },
])

repo

Required
Type: string

The name of the GitHub repository containing releases to load.

changelogsLoader([
  {
    repo: 'starlight-changelogs',
  },
])

token

Type: string

An optional GitHub fine-grained access token to use for loading releases which can be used to access private repositories or to increase the rate limit for public repositories.

The token should have the Contents repository permission (read).

changelogsLoader([
  {
    token: import.meta.env.GH_API_TOKEN,
  },
])

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