Skip to content
Starlight Tags

Configuring the Plugin

The starlight-tags plugin can be configured with the following options when added to your Starlight configuration.

Basic Configuration

Section titled “Basic Configuration”
astro.config.mjs
import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightTags from 'starlight-tags'


export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightTags({
          configPath: 'tags.yml',
          tagsPagesPrefix: 'tags',
          tagsIndexSlug: 'tags',
          onInlineTagsNotFound: 'warn',
          itemsPerPage: 12
        }),
      ],
      title: 'My Docs',
    }),
  ],
})

Configuration Options

Section titled “Configuration Options”

configPath

Section titled “configPath”
  • Type: string
  • Default: 'tags.yml'

Path to the tags configuration file relative to your Astro project root. This file defines all available tags and their metadata.

starlightTags({
  configPath: 'config/tags.yml', // Custom path
})

tagsPagesPrefix

Section titled “tagsPagesPrefix”
  • Type: string
  • Default: 'tags'

The URL prefix for individual tag pages. Each tag will be accessible at /{tagsPagesPrefix}/{tag-slug}.

starlightTags({
  tagsPagesPrefix: 'topics', // Tags at /topics/javascript, /topics/react, etc.
})

tagsIndexSlug

Section titled “tagsIndexSlug”
  • Type: string
  • Default: 'tags'

The URL slug for the tags index page that lists all available tags.

starlightTags({
  tagsIndexSlug: 'all-tags', // Index at /all-tags
})

onInlineTagsNotFound

Section titled “onInlineTagsNotFound”
  • Type: 'ignore' | 'warn' | 'error'
  • Default: 'warn'

How to handle tags used in page frontmatter that are not defined in your tags configuration file.

ValueBehavior
'ignore'Silently ignore undefined tags
'warn'Log a warning during build
'error'Fail the build with an error
starlightTags({
  onInlineTagsNotFound: 'error', // Strict mode - fail on undefined tags
})

itemsPerPage

Section titled “itemsPerPage”
  • Type: number
  • Default: 12

Number of items to display per page on individual tag pages. When a tag has more items than this limit, pagination controls will appear.

starlightTags({
  itemsPerPage: 20, // Show 20 items per page
})

URL structure with pagination:

  • First page: /tags/javascript/ (clean URL)
  • Page 2: /tags/javascript/2
  • Page 3: /tags/javascript/3

Example Configuration

Section titled “Example Configuration”

Here’s a complete example with all options:

astro.config.mjs
import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightTags from 'starlight-tags'


export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightTags({
          // Path to tags definition file
          configPath: 'tags.yml',


          // URL structure
          tagsPagesPrefix: 'tags',    // /tags/javascript
          tagsIndexSlug: 'tags',      // /tags


          // Validation
          onInlineTagsNotFound: 'warn',


          // Pagination
          itemsPerPage: 12
        }),
      ],
      title: 'My Documentation',
    }),
  ],
})

Internationalization (i18n)

Section titled “Internationalization (i18n)”

The plugin integrates with Starlight’s i18n system and provides built-in translations for English, French, Spanish, and German.

See the Internationalization guide for customizing translations or adding support for additional languages.

Next Steps

Section titled “Next Steps”