Skip to content
Starlight Versions

Getting Started

A Starlight plugin to version documentation pages. Check out the demo for a preview of the plugin in action.

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.

You will also need to have some documentation pages ready to be versioned. The plugin takes care of automatically archiving the current state of your documentation when you install it and create a new version. Check the “Versioning process” guide to learn more about how versioning works with the Starlight Versions plugin.

Installation

When ready to version your documentation pages, you can install and configure the Starlight Versions plugin.

  1. Starlight Versions is a Starlight plugin that you can install using your favorite package manager:

    Terminal window
    npm i starlight-versions

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

    The following example shows how to configure a single version 1.0 for your documentation:

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightVersions from 'starlight-versions'
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [
            starlightVersions({
              versions: [{ slug: '1.0' }],
            }),
          ],
          title: 'My Docs',
        }),
      ],
    })

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

    Update the content config file, adding a versions collection that uses Starlight Versions docsVersionsLoader:

    src/content.config.ts
    import { docsLoader } from '@astrojs/starlight/loaders'
    import { docsSchema } from '@astrojs/starlight/schema'
    import { defineCollection } from 'astro:content'
    import { docsVersionsLoader } from 'starlight-versions/loader'
    

    export const collections = {
      docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
      versions: defineCollection({ loader: docsVersionsLoader() }),
    }

  4. Start the development server to create the first version of your documentation.

    The current state of your documentation will be archived as the newly configured 1.0 version while you continue to work on the current version.

Learn more about versioning in the “Create a New Version” guide or how to configure the plugin in the configuration reference.