Skip to content

Usage

The Starlight Heading Badges plugin provides a custom Markdown syntax to add badges to your headings in Markdown and MDX files.

Add a badge

Badges are indicated using the colon : character followed by the badge keyword and the badge content in square brackets []. By default, the badge will use the theme accent color of your site.

The following example will render a “New” badge using the default theme accent color:

src/content/docs/example.md
---
title: My docs
---
### Example :badge[New]
Welcome to my project!
Preview

Example New

Welcome to my project!

Customize the badge

Heading badges support built-in badge variants to customize the appearance of the badge.

To specify a variant, add the variant name after the badge content in curly braces {} with the variant keyword and the variant name. The accepted variants are available: note (blue), tip (purple), danger (red), caution (orange), or success (green).

The following example will render a “POST” badge with a green background:

src/content/docs/example.md
---
title: My docs
---
### Example :badge[POST]{variant=success}
Welcome to my project!
Preview

Example POST

Welcome to my project!

Add multiple badges

Multiple badges can be added to the same heading by using the default syntax multiple times and separating badges with a space.

The following example will render a “POST” badge with a green background followed by a “New” badge using the default theme accent color:

src/content/docs/example.md
---
title: My docs
---
### Example :badge[POST]{variant=success} :badge[New]
Welcome to my project!
Preview

Example POST New

Welcome to my project!