Configuration

The starlight-announcement plugin accepts the following configuration options.

Basic Configuration

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({
          displayMode: 'stack',
          rotateInterval: 5000,
          announcements: [
            // Your announcements here
          ],
        }),
      ],
      title: 'My Docs',
    }),
  ],
})

Plugin Options

enabled

• Type: boolean
• Default: true

Controls whether announcements are displayed. Set to false to disable all announcements while keeping your configuration intact.

starlightAnnouncement({
  enabled: false, // Disable announcements
  announcements: [
    // Config preserved but not shown
  ],
})

displayMode

• Type: 'stack' | 'first' | 'rotate'
• Default: 'stack'

Controls how multiple active announcements are displayed. See Display Modes for details.

Mode	Behavior
stack	All active announcements shown vertically (default)
first	Only the first matching announcement is displayed
rotate	Carousel - cycles through announcements on interval

starlightAnnouncement({
  displayMode: 'first', // Only show one announcement at a time
})

rotateInterval

• Type: number
• Default: 5000
• Minimum: 500

Interval in milliseconds between announcement transitions when using rotate display mode.

starlightAnnouncement({
  displayMode: 'rotate',
  rotateInterval: 3000, // 3 seconds between transitions
})

showRotateIndicator

• Type: boolean
• Default: true

When using rotate display mode with multiple announcements, shows dot indicators below the banner. Users can click dots to jump to specific announcements, and the indicator supports keyboard navigation with arrow keys.

starlightAnnouncement({
  displayMode: 'rotate',
  showRotateIndicator: true, // Show navigation dots (default)
  // showRotateIndicator: false, // Hide navigation dots
})

iconSize

• Type: number
• Default: 24
• Range: 12 – 48

The size in pixels of the icon rendered in each announcement banner. Applies globally to all announcements.

starlightAnnouncement({
  iconSize: 32, // Larger icons
})

announcements

• Type: Announcement[]
• Default: []

Array of announcement objects. Each announcement has the following properties:

Property	Type	Required	Default	Description
id	string	Yes	-	Unique identifier (used for dismissal persistence)
content	string | Record<string, string>	Yes	-	The announcement text (supports HTML and localization)
variant	string	No	'note'	Visual style: note, tip, caution, danger
svgPath	string	No	-	SVG path d value to override the icon, or 'none' to hide it
dismissible	boolean	No	true	Whether users can dismiss the announcement
link	object	No	-	Optional CTA link with text (localizable) and href
startDate	string	No	-	ISO date when announcement becomes visible
endDate	string	No	-	ISO date when announcement stops being visible
showOn	string[]	No	['/**']	Glob patterns for pages to show on
hideOn	string[]	No	[]	Glob patterns for pages to hide from

See Announcement Options for detailed documentation of each property.

Complete Example

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({
          displayMode: 'stack',
          iconSize: 24,
          announcements: [
            {
              id: 'v3-migration',
              content: 'v3.0 has breaking changes!',
              variant: 'caution',
              link: {
                text: 'Migration Guide',
                href: '/guides/v3-migration',
              },
              dismissible: true,
              startDate: '2026-01-01',
              endDate: '2026-02-01',
              showOn: ['/**'],
              hideOn: ['/api/**'],
            },
            {
              id: 'welcome',
              content: 'Welcome to our new documentation site!',
              variant: 'tip',
              svgPath: 'M12 4L8 10H10V16H14V10H16L12 4M10 16L12 20L14 16',
              showOn: ['/'],
            },
          ],
        }),
      ],
      title: 'My Docs',
    }),
  ],
})

Next Steps

• Announcement Options: Detailed guide on variants, scheduling, and targeting
• Display Modes: How to control multiple announcement display
• Internationalization: Localized content for multilingual sites
• Custom Styling: Customize appearance with CSS