Defining Tags Schema

To use starlight-tags, you must create a tags.yml file that defines all available tags for your documentation site. This file serves as the schema for your tags, specifying their metadata, styling, and optional advanced properties.

By default, the plugin looks for tags.yml in your project root, but you can place it elsewhere (e.g., src/config/tags.yml) by setting the configPath option in your plugin configuration.

Why Define a Tags Schema?

Defining tags in a central schema file provides several benefits over using inline tags directly in frontmatter:

• Tag appearance (colors, icons, labels) stays uniform across all pages. Change a tag’s color once, and it updates everywhere.
• Typos in frontmatter are caught at build time. If you reference compnents instead of components, you’ll get a warning or error.
• Tags can have descriptions, custom permalinks, priority ordering, and educational properties that wouldn’t be possible with simple string tags.
• All tag definitions live in one place, making it easy to audit, update, or reorganize your taxonomy.
• Prerequisites, difficulty levels, and content types require schema definitions to work.
• New contributors can browse tags.yml to understand the available taxonomy without searching through pages.

Tag Validation

When a page references a tag that isn’t defined in your schema, the plugin can respond in different ways. Configure this behavior with the onInlineTagsNotFound option:

astro.config.mjs

starlightTagsPlugin({
  onInlineTagsNotFound: 'warn', // 'ignore' | 'warn' | 'error'
})

Value	Behavior
'ignore'	Silently skip undefined tags
'warn'	Log a warning but continue the build
'error'	Fail the build with an error

Using 'warn' or 'error' helps catch typos early and enforces your predefined taxonomy, preventing tag sprawl across your documentation.

Basic Structure

tags.yml

tags:
  components:
    label: "Components"
    description: "UI components and their usage patterns"
    color: "#3b82f6"
    icon: "🧩"

  configuration:
    label: "Configuration"
    description: "Setup options and config files"
    color: "#3b82f6"

defaults:
  color: "#6b7280"

Tag ID

The tag ID is the key used to reference the tag in frontmatter. It must:

• Contain only lowercase letters, numbers, hyphens, and underscores
• Be unique within your configuration

tags:
  my-tag:        # Valid: lowercase with hyphens
  my_tag:        # Valid: lowercase with underscores
  my-tag-123:    # Valid: lowercase with numbers
  "invalid tag": # Invalid: contains space
  MyTag:         # Invalid: uppercase letters not allowed

Tag Properties

Core Properties

Property	Type	Required	Description
label	string	Yes	Display name shown to users
description	string	No	Short description of the tag
color	string	No	Badge color (hex, named, rgb/hsl)
icon	string	No	Emoji or short text displayed with tag
permalink	string	No	Custom URL slug (overrides tag ID)
hidden	boolean	No	Hide from tag index (default: false)
priority	number	No	Sort order (higher appears first, default: 0)

label

The human-readable display name for the tag.

tags:
  i18n:
    label: "Internationalization"  # Shows as "Internationalization" in the UI

description

A brief description shown on the tag’s detail page and in tooltips.

tags:
  plugins:
    label: "Plugins"
    description: "Extending functionality with plugins and integrations"

color

The badge color. Supports multiple formats:

tags:
  # Hex colors (3, 6, or 8 digits)
  tag1:
    label: "Red"
    color: "#f00"

  tag2:
    label: "Blue"
    color: "#3178c6"

  # Named colors
  tag3:
    label: "Green"
    color: "green"

  # RGB/HSL functions
  tag4:
    label: "Custom"
    color: "rgb(255, 100, 50)"

icon

An emoji or short text displayed alongside the tag label.

tags:
  configuration:
    label: "Configuration"
    icon: "⚙️"

  markdown:
    label: "Markdown"
    icon: "📝"

permalink

Override the default URL slug (derived from tag ID).

tags:
  i18n:
    label: "i18n"
    permalink: "internationalization"  # Accessible at /tags/internationalization

hidden

Hide the tag from the tags index page. The tag remains functional and can still be used on pages.

tags:
  migration:
    label: "Migration"
    hidden: true  # Won't appear in /tags index

priority

Control the sort order of tags. Tags with higher priority values appear first. Tags with the same priority are sorted by page count (descending), then alphabetically by label.

tags:
  getting-started:
    label: "Getting Started"
    priority: 100  # Appears first

  guide:
    label: "Guide"
    priority: 50   # Appears second

  advanced:
    label: "Advanced"
    priority: 10   # Appears third

  troubleshooting:
    label: "Troubleshooting"
    # priority: 0 (default) - sorted by count, then alphabetically

Educational Properties

These optional properties support difficulty levels, content types, and prerequisite relationships:

Property	Type	Description
difficulty	'beginner' | 'intermediate' | 'advanced'	Complexity level
contentType	'lecture' | 'lab' | 'assignment' | 'project' | 'reference' | 'tutorial' | 'assessment'	Type of content
prerequisites	string[]	Tag IDs that should be understood first

Example with Educational Properties

tags:
  getting-started:
    label: "Getting Started"
    description: "Introduction to the library"
    color: "#f59e0b"
    icon: "🌱"
    difficulty: "beginner"
    contentType: "tutorial"

  advanced:
    label: "Advanced"
    description: "Advanced techniques and patterns"
    difficulty: "advanced"
    contentType: "reference"
    prerequisites:
      - getting-started
      - components

Defaults Section

Set default values for all tags:

tags:
  # ... tag definitions

defaults:
  color: "#6b7280"      # Default badge color

Default Properties

Property	Type	Default	Description
color	string	undefined	Default badge color for tags without an explicit color

Complete Example

Flexible Examples

This example demonstrates tags for a software library. The same structure works equally well for API docs, game engine docs, framework guides, or any other documentation type. Simply replace the tag names and descriptions to fit your domain.

tags.yml

tags:
  # Core feature tags
  components:
    label: "Components"
    description: "UI components and their usage patterns"
    color: "#3b82f6"
    icon: "🧩"

  configuration:
    label: "Configuration"
    description: "Setup options and config files"
    color: "#3b82f6"
    icon: "⚙️"

  theming:
    label: "Theming"
    description: "Styling, colors, and visual customization"
    color: "#3b82f6"
    icon: "🎨"

  # Integration tags
  plugins:
    label: "Plugins"
    description: "Extending functionality with plugins"
    color: "#8b5cf6"
    icon: "🔌"

  frameworks:
    label: "Frameworks"
    description: "Framework-specific usage (React, Vue, etc.)"
    color: "#8b5cf6"
    icon: "🏗️"

  deployment:
    label: "Deployment"
    description: "Hosting and deployment platforms"
    color: "#8b5cf6"
    icon: "🚀"

  # Content type tags
  guide:
    label: "Guide"
    description: "Step-by-step instructions"
    color: "#10b981"
    icon: "📖"

  reference:
    label: "Reference"
    description: "API and configuration reference"
    color: "#10b981"
    icon: "📚"

  # Audience tags
  getting-started:
    label: "Getting Started"
    description: "For new users starting out"
    color: "#f59e0b"
    icon: "🌱"

  advanced:
    label: "Advanced"
    description: "For experienced users"
    color: "#f59e0b"
    icon: "⚡"
    prerequisites: ["getting-started"]

defaults:
  color: "#6b7280"

Next Steps

• Learn how to add tags to pages using frontmatter
• Explore the auto-generated routes for tag pages
• See how to extend the schema with custom fields