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' | 'create'
• 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
'create'	Auto-create tags from frontmatter values

starlightTags({
  onInlineTagsNotFound: 'error', // Strict mode - fail on undefined tags
})

Auto-creating tags with 'create'

Setting this to 'create' tells the plugin to generate tag entries on the fly for any frontmatter tags that don’t exist in tags.yml:

starlightTags({
  onInlineTagsNotFound: 'create',
})

Auto-created tags only get a minimal set of properties:

• Label: derived from the frontmatter string (hyphens and underscores become spaces)
• Slug and URL: generated from the normalized tag ID
• Color: inherited from defaults.color in tags.yml, if present

Properties like icon, description, difficulty, and contentType won’t be set. If you need those, define the tag explicitly in tags.yml.

Spaces in tag names

In 'create' mode, spaces and underscores in frontmatter tags get normalized to hyphens for the tag ID, but the original string is kept as the label. For example, "Web Development" produces tag ID web-development with label “Web Development”.

No tags.yml required

With 'create' mode, the tags.yml file becomes entirely optional. If it doesn’t exist, all tags are created from frontmatter. You can still provide a tags.yml to customize specific tags while letting the rest be auto-created.

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

sidebar

• Type: false | SidebarConfig
• Default: false (disabled)

Automatically inject a “Popular Tags” group into Starlight’s navigation sidebar. This feature works without requiring any component overrides.

By default, sidebar injection is disabled. To enable it, provide a configuration object:

starlightTags({
  sidebar: {
    enabled: true,        // Enable sidebar injection
    position: 'top',      // 'top' or 'bottom' of sidebar
    limit: 10,            // Number of tags to show (0 = all)
    sortBy: 'count',      // 'count', 'alphabetical', or 'priority'
    showCount: true,      // Show page count badges
    collapsed: false,     // Start collapsed
    showViewAllLink: true // Include "View all tags" link
  }
})

Sidebar configuration options (when sidebar is provided):

Option	Type	Default	Description
enabled	boolean	true	Enable/disable sidebar injection (useful for toggling without removing config)
position	'top' | 'bottom'	'top'	Where to inject the tags group
limit	number	10	Max tags to show (0 = unlimited)
sortBy	'count' | 'alphabetical' | 'priority'	'count'	Sort order for tags
showCount	boolean	true	Show page count badge
collapsed	boolean	false	Start with group collapsed
showViewAllLink	boolean	true	Include link to tags index

The sidebar group uses localized labels from the plugin’s translation system (starlightTags.popularTags and starlightTags.viewAllTags).

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: 'ignore' | 'warn' | 'error' | 'create'
          onInlineTagsNotFound: 'warn',

          // Pagination
          itemsPerPage: 12,

          // Sidebar injection (optional)
          sidebar: {
            enabled: true,
            position: 'top',
            limit: 8,
            sortBy: 'count',
          }
        }),
      ],
      title: 'My Documentation',
    }),
  ],
})

Internationalization (i18n)

The plugin integrates with Starlight’s i18n system and provides:

• Built-in UI translations for English, French, Spanish, and German
• Localized tag labels and descriptions via object syntax in tags.yml

See the Internationalization guide for customizing translations, localizing tag content, 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