Formatting & Structure

Frontmatter Reference Guide

The frontmatter is the YAML block at the top of every Markdown file. It controls the page’s metadata, visibility, and behavior.

📝 Required Fields

Every page must have these fields to function correctly.

---
title: "Page Title"
---

Field	Type	Description
title	string	The main heading of the page. Shows in the browser tab, search results, and sidebar (unless overridden).

🔒 Access Control (Custom)

Control who can see your content. These are specific to our team site.

---
roles: ["Member"]
status: "published"
---

Field	Type	Default	Description
roles	array	['Guest']	Who can access this page. Options: Guest, Member, CoreTeam, Admin. Permissions cascade down (e.g., CoreTeam allows Admins too).
status	string	published	Lifecycle state. Options: draft (hidden), review (CoreTeam+), published (visible), archived (Admin only).
publishDate	date	-	Schedule a page to go public automatically on this date (ISO format YYYY-MM-DD).
archiveDate	date	-	Schedule a page to be archived automatically on this date.
archivedReason	string	-	Context for why a page was archived (displayed to Admins).

🧭 Navigation & Sidebar

Control where and how your page appears in the left-hand menu.

---
sidebar:
  label: "Short Name"
  order: 10
  badge:
    text: "New"
    variant: "tip"
---

Field	Type	Description
sidebar.label	string	Override the title for the sidebar menu link. Keep it short.
sidebar.order	number	Control the position in the menu. Lower numbers appear first.
sidebar.hidden	boolean	Set to true to hide from the sidebar entirely (page is still accessible via link).
sidebar.badge	object	Add a badge next to the link. properties: text (string), variant (note, tip, caution, danger, success, default).
category	string	Deprecated/Optional: Use folder structure for categorization primarily. Can be used for cross-cutting concerns.

ℹ️ Content Metadata

Additional details for SEO, search, and organization.

---
description: "A short summary for search engines."
tags: ["guide", "setup"]
lastUpdated: 2024-12-12
---

Field	Type	Description
description	string	A brief summary of the page content. Used for SEO and social previews.
tags	array	Keywords for categorization and search.
lastUpdated	date	Manually override the last updated date. If omitted, Git commit date is used.
pagefind	boolean	Set to false to exclude this page from site search results.

🎨 Visuals (Standard Starlight)

Customize the page appearance.

---
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 3
hero:
  title: "Welcome!"
  tagline: "Start here."
---

Field	Type	Description
tableOfContents	object or false	Configure the right-hand TOC. Use false to hide it.
hero	object	Display a large hero section at the top. Great for landing pages.
banner	object	Display a dismissal announcement banner at the top of the page.

Example: Full Configuration

Here is an example of a fully configured page:

---
title: "Quarterly Planning Guide"
description: "How to run the quarterly planning session for the Core Team."
roles: ["CoreTeam"]
status: "published"
tags: ["planning", "process"]
sidebar:
  label: "Planning Guide"
  order: 1
  badge:
    text: "Updated"
    variant: "success"
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 3
lastUpdated: 2025-01-15
---

## Introduction...