Docs Post

What Is This Page About?

Every file you place inside src/content/docs/ is a documentation page. Whether it is a simple intro, a deep-dive tutorial, or a reference section, each one is controlled by a block of frontmatter at the top of the file.

Frontmatter is the section between the two --- markers. It looks like this:

---
title: My Page
description: A short description of this page.
tableOfContents: true
---

The frontmatter tells Starlight how to render the page, where it appears in the sidebar, and what metadata to include for search engines.

This page explains every field you can use, what each one does, and when to use it.

---

Required Fields

These fields must be present on every docs page. Without them, the page will not build.

title

Type: string

Required: Yes

The page title. It appears in three places:

• The sidebar
• The browser tab
• The page metadata

title: Installation Guide

Every page must have a title. There are no exceptions.

---

Common Optional Fields

These fields are optional but used frequently. Most pages should include at least a description.

description

Type: string

Required: No

The page description. It is used for:

• SEO meta tags
• Social media previews (Open Graph, Twitter Cards)
• Search engine snippets

description: Learn how to install Astro Docus in five minutes.

A good description is one or two sentences — clear, specific, and useful for someone scanning search results.

---

Table of Contents

Control how the right-side navigation works for this page.

tableOfContents

Type: false | { minHeadingLevel?: number; maxHeadingLevel?: number }

Default: true (uses the global configuration)

This field overrides the global table of contents settings for a single page.

Hide the table of contents entirely:

tableOfContents: false

Customize which heading levels appear:

tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4

This example shows headings from ## (H2) through #### (H4). The default in Astro Docus is H2 through H3.

When to use false:

• Intro pages with no meaningful headings
• Splash pages designed as landing pages
• Pages where the right sidebar would feel cluttered

When to customize levels:

• Long reference pages with deep heading structure
• Pages where only the top-level sections matter

---

Layout Templates

Control the overall page structure.

template

Type: 'doc' | 'splash'

Default: 'doc'

Sets the layout template for the page.

Value	Description
'doc'	Standard documentation layout with sidebar
'splash'	Wide layout without sidebar, designed for landing pages

Use splash for:

• Welcome pages
• Landing pages within your docs
• Any page where you want maximum horizontal space

template: splash

The splash template works well with the hero component (see below).

---

Navigation Control

These fields control how the page behaves in the sidebar and pagination.

prev and next

Type: boolean | string | { link?: string; label?: string }

Default: true (uses global pagination)

Overrides the previous/next page navigation links at the bottom of the page.

Hide both links (common for standalone pages):

prev: false
next: false

Custom link:

prev:
  link: /custom-previous/
  label: Go Back

When to hide:

• Welcome pages
• Splash pages
• Any page that is not part of a linear sequence

sidebar fields (for autogenerated groups)

These fields only apply when the page is part of an autogenerated sidebar group (using autogenerate in astro.config.mjs).

sidebar.label

Type: string

Default: the page title

Overrides the label shown in the sidebar. Useful when the title is too long for the sidebar.

sidebar:
  label: Setup

sidebar.order

Type: number

Controls the sort order within an autogenerated group. Lower numbers appear first.

sidebar:
  order: 1

This is an alternative to using numbered filename prefixes. It works the same way but keeps the URL clean.

sidebar.hidden

Type: boolean

Default: false

Hides the page from autogenerated sidebar groups, even though the page is still accessible by URL.

sidebar:
  hidden: true

Useful for pages that are linked internally but should not clutter the sidebar.

sidebar.badge

Type: string | BadgeConfig

Adds a visual badge next to the page in the sidebar.

Simple badge:

sidebar:
  badge: New

Custom badge with variant:

sidebar:
  badge:
    text: Updated
    variant: tip

Available variants: note, tip, caution, danger, success, default.

sidebar.attrs

Type: Record<string, string | number | boolean | undefined>

Adds HTML attributes to the sidebar link. Merged with any autogenerate.attrs set on the group.

sidebar:
  attrs:
    target: _blank

---

Search Control

pagefind

Type: boolean

Default: true

Controls whether the page is included in the Pagefind search index.

pagefind: false

When to exclude:

• Thank-you pages
• Internal test pages
• Any page that should not appear in search results

---

Draft Pages

draft

Type: boolean

Default: false

Marks the page as a draft. Draft pages are only visible during development and are excluded from production builds.

draft: true

Important: Draft pages are also excluded from autogenerated sidebar groups in production. You cannot add a draft page to the sidebar using its slug.

Workflow:

1. Write your page with draft: true
2. Preview it locally with npm run dev
3. When ready to publish, remove the draft: true line
4. Build for production with npm run build

---

Content Customization

head

Type: HeadConfig[]

Adds extra tags to the page’s <head> section.

head:
  - tag: title
    content: Custom About Title
  - tag: meta
    attrs:
      name: custom-meta
      content: custom-value

Use for:

• Custom page titles (different from the sidebar title)
• Page-specific meta tags
• Additional stylesheets
• Custom Open Graph overrides

banner

Type: { content: string }

Displays an announcement banner at the top of the page.

banner:
  content: We just released a new feature! <a href="/blog/new-feature/">Learn more</a>

The content value supports HTML, so you can include links and basic formatting.

When to use:

• Announcing new features
• Temporary notices
• Highlighting important updates

hero

Type: HeroConfig

Adds a hero component to the top of the page. Works best with template: splash.

template: splash
hero:
  title: Astro Docus
  tagline: Documentation, blog, and landing in one template.
  image:
    file: ../../assets/astrodocus-hero.png
    alt: Astro Docus hero illustration
  actions:
    - text: Get Started
      link: /getstart/
      icon: right-arrow
      variant: primary
    - text: View on GitHub
      link: https://github.com/example/astrodocus
      icon: external
      variant: secondary

When to use:

• Homepage of your documentation
• Major section landing pages
• Welcome pages

editUrl

Type: string | boolean

Overrides the global edit link for this page.

editUrl: https://github.com/your/repo/edit/main/docs/custom-page.md

Set to false to disable:

editUrl: false

When to use:

• Pages with a different edit location
• Pages that should not be edited by contributors
• Auto-generated pages

lastUpdated

Type: Date | boolean

Overrides the global last-updated date for this page.

lastUpdated: 2025-01-15

Set to false to hide:

lastUpdated: false

When to use:

• Manually dated pages
• Pages where Git history is not available
• Pages that should not show an update date

---

Hidden Gems

These fields are less commonly used but powerful in specific situations.

slug

Type: string

Overrides the URL slug for the page. The file path determines the default slug, but this field lets you customize it.

slug: my-custom-url

If the file is src/content/docs/getstart/installation.md, the default URL is /getstart/installation/. With slug: setup, it becomes /setup/.

Use sparingly — changing slugs can break existing links.

hero image configuration

The hero field supports different images for light and dark modes:

hero:
  image:
    alt: Astro Docus logo
    dark: ../../assets/logo-dark.png
    light: ../../assets/logo-light.png

This ensures the hero image looks good regardless of the user’s theme preference.

---

Frontmatter in Content Collections

Astro Docus uses the docsSchema() helper to define the frontmatter schema for the docs collection. This is configured in src/content/config.ts (or src/content.config.ts).

Extending the Schema

You can add custom fields to the frontmatter schema using the extend option:

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

export const collections = {
  docs: defineCollection({
    schema: docsSchema({
      extend: z.object({
        category: z.string().optional(),
      }),
    }),
  }),
};

Now every docs page can include a category field in its frontmatter, and it will be type-checked.

---

Quick Reference Table

Field	Type	Default	Purpose
title	string	Required	Page title
description	string	—	SEO description
tableOfContents	false | object	true	Control TOC
template	'doc' | 'splash'	'doc'	Layout template
prev	boolean | string | object	true	Previous page link
next	boolean | string | object	true	Next page link
sidebar.label	string	title	Sidebar label
sidebar.order	number	—	Sort order
sidebar.hidden	boolean	false	Hide from sidebar
sidebar.badge	string | object	—	Sidebar badge
pagefind	boolean	true	Search inclusion
draft	boolean	false	Draft mode
head	HeadConfig[]	—	Custom head tags
banner	{ content: string }	—	Announcement banner
hero	HeroConfig	—	Hero component
editUrl	string | boolean	—	Edit link override
lastUpdated	Date | boolean	—	Update date
slug	string	—	URL slug override

---

Common Patterns

Standard documentation page

---
title: Installation
description: How to install Astro Docus.
---

Intro / landing page

---
title: Get Started
description: Introduction to Astro Docus.
template: splash
tableOfContents: false
prev: false
next: false
---

Draft page

---
title: Work in Progress
description: This page is not ready yet.
draft: true
---

Page with custom sidebar order

---
title: Advanced Configuration
description: Deep customization options.
sidebar:
  order: 10
---

Page with badge

---
title: New Feature
description: Just released.
sidebar:
  badge:
    text: New
    variant: tip
---

Page excluded from search

---
title: Thank You
description: Your purchase is confirmed.
pagefind: false
prev: false
next: false
---

---

Rules to Remember

1. title is always required. Every page needs one.
2. description is strongly recommended. It powers SEO and social previews.
3. Use splash template for landing pages. Combine with hero for best results.
4. Hide prev/next on standalone pages. Welcome, thank-you, and splash pages should not have pagination.
5. Set draft: true while writing. Remove it when ready to publish.
6. Use sidebar.order instead of filename prefixes if you prefer clean URLs.
7. pagefind: false for pages that should not be searchable.
8. tableOfContents: false for pages without meaningful headings.

---

Quick Recap

Required:
  title

Common:
  description
  tableOfContents
  template (doc | splash)
  prev / next

Navigation:
  sidebar.label
  sidebar.order
  sidebar.hidden
  sidebar.badge

Content:
  head
  banner
  hero
  editUrl
  lastUpdated

Hidden:
  slug
  pagefind
  draft

Frontmatter is the control panel for every documentation page. Master it, and you control exactly how each page appears, behaves, and integrates with the rest of your site.