Starlight Frontmatter Cheatsheet

Starlight frontmatter controls how each docs page looks and where it appears: its title and description, the layout template, an optional hero and banner, its sidebar label, order and badge, the table of contents, previous/next links, search indexing and draft status. Only title is required. This cheatsheet lists every field from Starlight’s frontmatter reference with its type and a short example.

Key Takeaways

• title is the only required field.
• template: splash gives a full-width landing layout, usually paired with hero.
• sidebar.order, sidebar.label, sidebar.badge and sidebar.hidden control autogenerated sidebars.
• draft: true keeps a page out of production builds; pagefind: false keeps it out of search.

Minimal page

---
title: Install the CLI
description: Install the command-line tool with npm, pnpm or Bun.
---

Content starts here.

All fields

Field	Type	Default	Purpose
title	string	required	Page heading, browser tab, metadata
description	string	none	Meta description and social previews
slug	string	from file path	Override the page’s URL
editUrl	string | boolean	global editLink	Custom edit link, or false to hide it
head	HeadConfig[]	none	Extra tags for this page’s <head>
tableOfContents	false | { minHeadingLevel?, maxHeadingLevel? }	global setting	Heading levels shown, or hide it
template	'doc' | 'splash'	'doc'	Layout; splash has no sidebars
hero	HeroConfig	none	Hero section at the top of the page
banner	{ content: string }	none	Announcement banner; content can include HTML
lastUpdated	Date | boolean	global setting	Override or hide the last-updated date
prev	boolean | string | { link?, label? }	global pagination	Previous link: hide, relabel, or replace
next	boolean | string | { link?, label? }	global pagination	Next link, same options
pagefind	boolean	true	Include in Pagefind search
draft	boolean	false	Exclude from production builds
sidebar	SidebarConfig	none	Label, order, badge, visibility, attributes

Sidebar

sidebar:
  label: CLI install       # defaults to the page title
  order: 2                 # lower numbers appear first
  badge:
    text: New
    variant: tip
  hidden: false
  attrs:
    class: highlighted

Field	Type	Default
sidebar.label	string	page title
sidebar.order	number	none
sidebar.hidden	boolean	false
sidebar.badge	string | BadgeConfig	none
sidebar.attrs	Record<string, string | number | boolean | undefined>	none

A string badge (badge: New) uses the default accent colour. These options apply to autogenerated sidebar groups.

Splash page with a hero

---
title: Acme Docs
template: splash
hero:
  title: Build with Acme
  tagline: Guides, references and examples for the Acme API.
  image:
    file: ../../assets/hero.png
    alt: Acme dashboard
  actions:
    - text: Get started
      link: /getting-started/
      icon: right-arrow
      variant: primary
    - text: View on GitHub
      link: https://github.com/acme/acme
      icon: external
      variant: minimal
---

hero.image accepts one of three shapes: file (with alt), separate dark and light files (with alt), or raw html. Action variant is primary, secondary or minimal.

Table of contents

tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4

tableOfContents: false

Previous and next links

prev: false                              # hide
next: Continue to deployment             # relabel only
next:
  link: /guides/deploy/
  label: Deploy your docs                # replace both

Banner, last updated, edit link

banner:
  content: Version 3 is out. <a href="/upgrade/">Read the upgrade guide</a>.
lastUpdated: 2026-10-01
editUrl: false

Custom head tags

head:
  - tag: title
    content: Custom browser title
  - tag: meta
    attrs:
      name: robots
      content: noindex

Adding your own fields

Extend the schema in src/content.config.ts:

import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
import { z } from 'astro/zod';

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({
      extend: z.object({ audience: z.enum(['beginner', 'advanced']).optional() }),
    }),
  }),
};

Starlight builds on Astro content collections, so the content collections cheatsheet applies to it too. If you’re deciding between Starlight and a themed docs site, compare with the documentation themes and the Astro content collections guide. Starlight’s own frontmatter reference is the source for this page.

FAQ

How do I hide a page from the Starlight sidebar?

Set sidebar.hidden: true. The page still builds and is reachable by URL.

How do I order pages in an autogenerated sidebar?

Give each page a sidebar.order number. Lower numbers appear higher in the group.