Frontmatter reference

Frontmatter is not decoration. It drives the sidebar, the search index, the difficulty badges, the review cadence and maintainer routing. The schema is defined in content.config.json and validated by pnpm content:validate.

A complete example

---
id: interactive-rebase
title: Interactive rebase
sidebar_label: Interactive rebase
sidebar_position: 40
description: Reorder, squash, edit and drop commits using the interactive rebase todo list.
keywords:
  - rebase
  - interactive
  - squash
tags:
  - walkthrough
  - rebasing
  - individual
module: 05-history-and-rewriting
level: advanced
duration: 35
status: published
last_reviewed: 2026-07-22
maintainers:
  - nabin747
prerequisites:
  - rebase-basics
  - commit-anatomy
git_version: "2.38"
---

Required fields

Field	Type	Constraint	What breaks without it
id	string	kebab-case, no ordering prefix	Cross-references cannot resolve the document
title	string	4–70 chars, sentence case, no trailing period	The H1 and every link title
description	string	60–170 chars, one sentence	Search snippets and social previews fall back to the first paragraph
module	enum	must match the containing directory	Aggregate views silently omit the document
level	enum	foundational · intermediate · advanced · expert	Difficulty filtering and the badge
duration	integer	0–180 minutes	Time estimates in <LessonMeta> and module totals
status	enum	see below	Draft content leaks into published navigation
last_reviewed	date	YYYY-MM-DD, not in the future	The staleness audit cannot run
maintainers	array	≥1 GitHub handle, no @	Nobody is routed the review

Recommended fields

Field	Type	Notes
sidebar_label	string	≤32 characters. Set it whenever title would wrap in the sidebar
keywords	array	1–10 terms; feeds the local search index
tags	array	≤6, drawn from the closed taxonomy below

Optional fields

sidebar_position, slug, prerequisites, git_version, hide_table_of_contents, hide_title, pagination_prev, pagination_next, image, unlisted, draft, toc_min_heading_level, toc_max_heading_level.

Forbidden fields

sidebar, author, date.

Authorship is Git history, not metadata — a document with five contributors and one author field is actively misleading. date duplicates showLastUpdateTime, which is derived from commits and therefore cannot drift.

Status values

Status	Meaning	Appears in navigation
scaffolded	File exists, no content yet	Yes, visibly empty
draft	Being written	Yes
in-review	Open pull request	Yes
published	Reviewed and verified	Yes
needs-update	Known to be stale or wrong	Yes, with a banner
deprecated	Superseded; kept for its URL	Yes, with a redirect notice

Tag taxonomy

The vocabulary is closed. An unknown tag fails validation. Adding one is a deliberate change to content.config.json, reviewed on its own merits — this is what stops a tag list from degenerating into four hundred synonyms.

Content type — module-overview, concept, walkthrough, exercise, lab, cheatsheet, reference, glossary-entry, troubleshooting, decision-guide, landing

Topic — setup, configuration, objects, refs, index, commits, branches, merging, rebasing, remotes, tags, stashing, hooks, submodules, worktrees, large-repos, security, signing, ci, recovery, performance

Audience — individual, team, maintainer, platform-engineer

The YAML dialect

The parser in scripts/lib/frontmatter.mjs accepts a deliberately narrow subset: scalars, ISO dates, quoted strings, inline arrays and block arrays.

Anchors, block scalars (|, >), inline maps and multi-line flow scalars are rejected. That is intentional: they make frontmatter hard to diff and review, and nothing here needs them.