Skip to content
Starlight Announcement
Welcome to starlight-announcement plugin! Get Started

Getting Started

A Starlight plugin that adds enhanced announcement banners with dismissibility, variants, scheduling, and page targeting. These features are missing from the built-in Banner component.

Prerequisites

Section titled “Prerequisites”

You will need to have a Starlight website set up. If you don’t have one yet, you can follow the “Getting Started” guide in the Starlight docs to create one.

Installation

Section titled “Installation”

  1. starlight-announcement is a Starlight plugin. Install it by running the following command in your terminal:

    Terminal window
    npm install starlight-announcement

  2. Configure the plugin in your Starlight configuration in the astro.config.mjs file.

    astro.config.mjs
    import starlight from '@astrojs/starlight'
    import { defineConfig } from 'astro/config'
    import starlightAnnouncement from 'starlight-announcement'
    

    export default defineConfig({
      integrations: [
        starlight({
          plugins: [
            starlightAnnouncement({
              announcements: [
                {
                  id: 'welcome',
                  content: 'Welcome to our documentation!',
                  variant: 'tip',
                },
              ],
            }),
          ],
          title: 'My Docs',
        }),
      ],
    })

  3. Start the development server to preview the plugin in action.

Basic Example

Section titled “Basic Example”

Here’s a simple configuration with multiple announcements:

astro.config.mjs
import starlight from '@astrojs/starlight'
import { defineConfig } from 'astro/config'
import starlightAnnouncement from 'starlight-announcement'


export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightAnnouncement({
          announcements: [
            {
              id: 'v2-release',
              content: 'Version 2.0 is now available!',
              variant: 'tip',
              link: {
                text: 'See changelog',
                href: '/changelog',
              },
            },
            {
              id: 'breaking-changes',
              content: 'Breaking changes in the API.',
              variant: 'caution',
              dismissible: true,
            },
          ],
        }),
      ],
      title: 'My Docs',
    }),
  ],
})

Verify Installation

Section titled “Verify Installation”

After completing the setup, start your development server and you should see:

  1. A colored banner at the top of every page (below the header)
  2. A dismiss button (X) on the right side of the banner
  3. The banner disappears after clicking dismiss and stays hidden on page reload

What You Get

Section titled “What You Get”

After installation, the plugin automatically:

  • Displays announcements at the top of every page (or targeted pages)
  • Persists dismissals in localStorage so users don’t see dismissed announcements again
  • Respects scheduling if you set startDate or endDate
  • Applies page targeting if you use showOn or hideOn patterns

Next Steps

Section titled “Next Steps”