Frontmatter and dates

Starlight’s built-in fields plus the small set of custom fields this repo adds. Copy the block you need at the top of a new post.

---

The full frontmatter I actually use

post.md

---
title: RBAC Basics
description: Role-based access control on Kubernetes — Roles, ClusterRoles, and least-privilege ServiceAccounts.
date: 2026-07-30                    # custom — sortable; shown only when showDate is true
pubDate: 2026-07-30                  # custom — alternative to date, either works
showDate: true                       # custom — opt in to render date under title + in Recent Posts
draft: false                         # custom — hides from Recent Posts if true
tags: [kubernetes, security, rbac]   # custom — free-form array
sidebar:
  order: 1                           # sort order within the parent group
  label: RBAC                        # override the sidebar label (default = title)
  badge:                             # inline badge next to the sidebar item
    text: Lab
    variant: tip                     # note | tip | danger | caution | success
  hidden: false                      # hide this page from the sidebar entirely
prev: true                           # true (default) | false | { label, link }
next: false
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 3
pagefind: true                       # false to exclude from search
---

---

Dates: which field, what shows up

Two custom fields — date and pubDate — behave the same. Pick one and stick with it. Both drive the sort order of Recent Posts, but the date only renders visually when you opt in.

How dates surface (opt-in)

• Recent Posts (home) sorts by date (fallback pubDate), newest first — always.
• Rendered date appears next to the title in Recent Posts and under the H1 on the post itself — only when showDate: true.
• Default is off. Set showDate: true in frontmatter to turn it on for a specific post.

Why opt-in

Most reference material is timeless. Adding a date to every page ages content prematurely. For posts where “this is what I learned in Q3 2026” matters (e.g. release notes, changelogs), flip showDate: true.

ISO 8601, please

Always YYYY-MM-DD. Time-of-day and timezone are optional but supported (2026-07-30T14:30:00Z). Zod-based schema coerces the string; a typo throws at build time.

Schema definition (see content.config.ts):

src/content.config.ts

export const collections = {
  docs: defineCollection({
    loader: docsLoader(),
    schema: docsSchema({
      extend: z.object({
        date: z.coerce.date().optional(),
        pubDate: z.coerce.date().optional(),
        draft: z.boolean().optional(),
        tags: z.array(z.string()).optional(),
        showDate: z.boolean().optional(),
      }),
    }),
  }),
};

---

Sidebar order + labels

Autogenerated sidebars sort alphabetically by filename by default. Override with sidebar.order:

post.md

---
title: RBAC Basics
sidebar:
  order: 1        # smaller = higher
  label: RBAC     # shorter than the page title, if you want
---

Ordering ties

Files without sidebar.order sort after ordered ones, then alphabetically. When two files share an order, filename is the tiebreaker.

---

Badges

Two places you can add badges: on the sidebar entry and inline in the body.

Sidebar badge

post.md

---
title: RBAC Basics
sidebar:
  badge:
    text: Lab
    variant: tip
---

Body badge

post.mdx

import { Badge } from '@astrojs/starlight/components';

<Badge text="Lab scenario" variant="tip" size="medium" />

Variants: note, tip, danger, caution, success (+ default).

---

Previous / Next controls

By default Starlight shows prev/next links based on sidebar order. Frontmatter overrides:

disable-both.md

---
prev: false
next: false
---

custom-link.md

---
title: A follow-up post
prev:
  label: Kubernetes overview
  link: /kubernetes/
next:
  label: Networking
  link: /kubernetes/networking/
---

What actually renders

• Both defined + both in-sidebar → both links show.
• Only prev in-sidebar → only prev shows (the “no next” case is silent).
• prev: false → hides prev link even if one exists.
• Landing pages (index.mdx) typically want prev: false and next: false.

---

Table of contents

post.md

---
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 3   # skip h4 and deeper
---

Or hide it entirely:

tableOfContents: false

---

Draft, hidden, search

Three ways to make a page 'less visible'

• draft: true → your custom field. Filters out of Recent Posts; page still builds.
• sidebar.hidden: true → Starlight built-in. Hides from sidebar; page still builds.
• pagefind: false → excludes from the search index.
• Really don’t publish? Move it out of src/content/docs/.

---

Hero (landing-page splash)

For big landing pages, Starlight has a built-in hero renderer:

index.mdx

---
title: Kubernetes
description: Notes on running production-grade Kubernetes.
template: splash                # use Starlight's splash template
hero:
  tagline: Security, networking, and lab scenarios.
  image:
    file: ../../../assets/heroes/kubernetes.svg
    alt: Kubernetes hero
  actions:
    - text: Start with Security
      link: /kubernetes/security/
      icon: right-arrow
      variant: primary
---

Not this site's default

This site uses a compact, doc-style landing (no hero). If you want a splash hero on a new section, add template: splash — Starlight handles the rest.

---

Everything else

Field	Purpose
template	doc (default) or splash (hero + CTAs).
lastUpdated	true to show git-based mtime; ISO string to override.
editUrl	true to auto-emit “Edit this page”; false to hide.
head	Inject extra <head> tags (SEO, canonical, etc.).
banner	{ content: 'string' } — page-wide announcement.