Add a sitewide banner to Starlight

Starlight provides an out-of-the-box feature to display an announcement banner at the top of a specific page. Such a feature is configured per page and is not meant to be used to display a sitewide banner.

This guide will show you how to re-use this feature to display a sitewide banner on all pages of your Starlight documentation website.

Sitewide banners

Compared to page-specific banners, sitewide banners usually involve a lot more considerations which explains why they are not a built-in feature of Starlight so far.

Such banners which are always visible on all pages may catch too much attention and could end up being annoying to users if a mechanism to dismiss them is not provided. Starlight internationalization support would also need to be considered to display the banner in multiple languages.

However, there are still valid use cases for sitewide banners such as maintenance notifications, important announcements, etc. One example of a sitewide banner I use is on the Starlight TypeDoc plugin demo website (which is different from the plugin documentation) to display a message reminding users that the website is a demo with a link to the plugin documentation.

Prerequisites

You will need to have an existing Starlight website.

Frontmatter schema

The Starlight per-page banner feature is configured using the banner field in the frontmatter of a Markdown or MDX page. The content value defines the text to display in the banner.

---
title: Page with a banner
banner:
  content: Welcome to the new version of our documentation!
---

Starlight is built on top of Astro’s content collections and the frontmatter schema used for your documentation can be configured in the src/content/config.ts file. The default frontmatter schema can be extended to add support for additional fields or tweak the existing ones.

By using such a mechanism, it is possible to add a default value for the existing banner field which would automatically be used when a page does not specify a banner and thus provide a sitewide banner.

import { defineCollection, z } from 'astro:content'
import { docsSchema } from '@astrojs/starlight/schema'

export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      extend: z.object({
        // Add a default value to the built-in `banner` field.
        banner: z.object({ content: z.string() }).default({
          content: 'This documentation is in construction.',
        }),
      }),
    }),
  }),
}

The code above would add the following banner to all pages not explicitly specifying a banner:

You can find the complete source code of this guide in this StackBlitz example.