Zum Inhalt springen
Starlight Tags

Using Page Frontmatter

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Add tags to your documentation pages by including them in the page’s frontmatter. The plugin provides tag-related frontmatter properties that integrate with Starlight’s content schema.

Schema Setup

Section titled “Schema Setup”

To enable tag frontmatter validation and TypeScript support, extend your content collection schema in src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
import { starlightTagsExtension } from 'starlight-tags';


export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({ extend: starlightTagsExtension })
  })
};

This step is optional but recommended. Without it, tag frontmatter will still work but you won’t get TypeScript validation or autocompletion for tag-related fields.

Basic Usage

Section titled “Basic Usage”

Add tags to any page by including a tags array in the frontmatter:

---
title: Configuration Guide
tags:
  - configuration
  - guide
  - getting-started
---


Your page content here...

You can also use inline array syntax: tags: [configuration, guide, getting-started]

Frontmatter Properties

Section titled “Frontmatter Properties”

tags

Section titled “tags”
  • Type: string[]
  • Default: undefined

An array of tag IDs to associate with the page. Tag IDs must match those defined in your tags.yml configuration file.

---
title: Plugin Development Guide
tags:
  - plugins
  - advanced
  - guide
---

featuredTags

Section titled “featuredTags”
  • Type: string[]
  • Default: undefined

Highlight specific tags as featured. Featured tags may be displayed more prominently depending on your component configuration.

---
title: Configuration Guide
tags:
  - configuration
  - guide
  - getting-started
featuredTags:
  - configuration
---

hideTags

Section titled “hideTags”
  • Type: boolean
  • Default: false

Hide the tags display on this specific page. The page will still be associated with its tags (appearing on tag pages), but tags won’t be rendered on the page itself.

---
title: Internal Documentation
tags:
  - troubleshooting
hideTags: true
---

Both the PageTags and PageWithTags components respect this property and will render nothing when hideTags: true.

tagsPosition

Section titled “tagsPosition”
  • Type: 'top' | 'bottom' | 'both'
  • Default: 'bottom'

Control where tags are displayed on the page.

---
title: Components Reference
tags:
  - components
tagsPosition: top
---
ValueDescription
'top'Display tags at the top of the content
'bottom'Display tags at the bottom of the content
'both'Display tags at both top and bottom

Validation

Section titled “Validation”

When you use a tag that isn’t defined in your tags.yml, the plugin’s behavior depends on your configuration:

  • 'warn' (default): Logs a warning during build
  • 'error': Fails the build
  • 'ignore': Silently ignores undefined tags

Examples

Section titled “Examples”

Minimal Example

Section titled “Minimal Example”
---
title: Quickstart
tags:
  - getting-started
---

Full Example

Section titled “Full Example”
---
title: Advanced Plugin Development
description: Complete guide to building custom plugins
tags:
  - plugins
  - advanced
  - guide
  - components
featuredTags:
  - plugins
tagsPosition: top
---


import { PageTags } from 'starlight-tags/components';


# Advanced Plugin Development


<PageTags />


Your content here...

Reference Page

Section titled “Reference Page”
---
title: Component Reference
tags:
  - components
  - reference
  - frameworks
---


Complete reference for all available components.

Using Tags in Content

Section titled “Using Tags in Content”

You can also display tags manually within your content using the exported components:

---
title: Plugin Development Guide
tags:
  - plugins
  - guide
---


import { PageTags, TagBadge } from 'starlight-tags/components';


# Plugin Development Guide


<PageTags layout="inline" />


Content goes here...


Or display a specific tag:


<TagBadge tagId="plugins" />

Next Steps

Section titled “Next Steps”