Configuration

The Starlight Versions plugin can be configured inside the astro.config.mjs configuration file of your project:

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({
          // Configuration options go here.
        }),
      ],
      title: 'My Docs',
    }),
  ],
})

Configuration options

The Starlight Versions plugin accepts the following configuration options:

versions

Required
Type: StarlightVersionConfig[]

A list of all archived versions of the documentation. See the version configuration section or the “Create a New Version” guide for more details.

current

Type: StarlightCurrentVersionConfig

The configuration for the current version of the documentation. See the current version configuration section for more details.

exclude

Type: string[]
Default: []

A list of source file glob patterns for pages that should be excluded from versioning. Excluded pages use the latest content regardless of the selected version.

Patterns are relative to the src/content/docs/ directory, for example internal/** excludes all pages in the src/content/docs/internal/ directory from versioning.

Version configuration

A version configuration object is used to define a version.

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightVersions({
          versions: [
            {
              slug: '1.0',
              label: 'v1.0',
            },
          ],
        }),
      ],
    }),
  ],
})

The following properties are supported by a version configuration object:

slug

Required
Type: string

The version slug used in URLs to identify the version and its content, e.g. 1.0 or 2-1-0.

label

Type: string
Default: the version slug

An optional label used in the UI when displaying the version, e.g. v1.0. If not provided, the version slug is used.

redirect

Type: 'same-page' | 'root'
Default: 'same-page'

The version redirect strategy used when navigating to this version.

Current version configuration

The current version can be configured using the current option.

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightVersions({
          current: {
            label: 'v3.0',
          },
        }),
      ],
    }),
  ],
})

The current version can be configured using the following properties:

label

Type: string
Default: 'Latest'

An optional label used in the UI for the current version.

redirect

Type: 'same-page' | 'root'
Default: 'same-page'

The version redirect strategy used when navigating to the current version.

Redirect strategies

When navigating to a different version, the plugin supports two redirect strategies:

• same-page: Redirect to the same page when navigating to this version.
• root: Redirect to the root page of the documentation when navigating to this version.