Getting Started

A Starlight plugin to display changelogs alongside your project documentation:

• Load changelogs using multiple providers, such as changelog files generated by Changesets or GitHub releases.
• List all versions in paginated pages.
• Display each version’s changelog in a dedicated page.
• Generate pages to list all changes from a specific version to the latest version.

Check out the demo for a preview of various changelog pages generated by the plugin.

Prerequisites

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

1. Starlight Changelogs is a Starlight plugin. Install it using your favorite package manager:

   npm

   npm i starlight-changelogs

   pnpm

   pnpm add starlight-changelogs

   yarn

   yarn add starlight-changelogs

   ni

   ni starlight-changelogs

2. Add the plugin to your Starlight configuration in the astro.config.mjs file.

   astro.config.mjs

   // @ts-check
   import starlight from '@astrojs/starlight'
   import { defineConfig } from 'astro/config'
   import starlightChangelogs from 'starlight-changelogs'
   
   export default defineConfig({
     integrations: [
       starlight({
         plugins: [starlightChangelogs()],
         title: 'My Docs',
       }),
     ],
   })

3. Starlight Changelogs uses Astro’s content collections, which are configured in the src/content.config.ts file.

   Update the content config file to add support for generating changelog pages:

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

4. Starlight Changelogs is entirely configured using the changelogsLoader() loader previously added to the the src/content.config.ts file.

   For example, the following configuration adds support for loading a changelog file generated by Changesets using its file path relative to the root of the Starlight project. The generated changelog pages will be available under the /changelog/ path.

   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',
           base: 'changelog',
           changelog: '../packages/my-packages/CHANGELOG.md',
         },
       ]),
     }),
   }

   To learn more about the various providers supported by the plugin and how to configure them, check out the “Providers” section of the documentation.

5. With a first changelog configured, start the development server and visit the URL matching the base path you configured in the previous step, e.g. /changelog/.

   You should see a paginated changelog overview page listing all versions, with links to each version’s changelog page.