Configuring the Plugin

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

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

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

• 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

• 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

• Type: 'ignore' | 'warn' | 'error'
• Default: 'warn'

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

Value	Behavior
'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

• 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

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)

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

• Learn how to define tags in your tags.yml file
• See how to add tags to pages using frontmatter
• Explore the auto-generated routes created by the plugin