Frontmatter Schema

Every .md file in docs/ must open with a YAML frontmatter block. Each field has exactly one primary consumer: Docusaurus or the doc-update bot.

The "edited by … on …" bar shown at the bottom of every page is not a frontmatter field — it is derived from git history at build time (showLastUpdateAuthor / showLastUpdateTime). The author is the last commit's git author (the PR opener after a squash-merge) and the date is when the change landed on main.

Canonical template

---
title: ""
description: ""
covers: []
---

Paste this at the top of every new page. Fill covers before opening a PR.

---

Fields

title

Consumer: Docusaurus Required: yes

The page title as it appears in the browser tab, search index, and link previews. Must agree with the H1 heading on the page.

Conventions per doc type:

Doc type	Convention	Example
Reference	Feature or component name	"Token Manager"
How-to	Action phrase starting with a verb	"Add a REST Endpoint"
Runbook	Incident or procedure name	"Sevalla Deployment Rollback"
ADR	ADR-NNNN: prefix + short title	"ADR-0003: Migrate from MkDocs to Docusaurus"

Malformed if: missing, empty string, or an ADR page whose title does not match ADR-\d{4}:.

---

description

Consumer: doc-update bot + search engines Required: yes (empty string is valid during authoring)

One sentence summarising what this page covers. The bot reads this to understand a page's scope without reading the full content — it is the primary signal the bot uses to decide whether a page is relevant to a given code change. Search engines use it as the meta description.

Keep it under 160 characters. Do not use newlines.

Malformed if: longer than 160 characters, or contains a newline.

---

covers

Consumer: doc-update bot Required: yes ([] is valid)

Codebase package paths this page documents. The bot uses this for routing: when a codebase PR's "Docs to update" field is blank it is the router (the matched pages are drafted), and when pages are declared it is an audit (a matched page the developer did not list is flagged on the code PR, not drafted). When the bot creates a new page, or edits a page whose covers: is empty, it fills this field from the PR's changed packages and flags the value for review — but it never modifies a non-empty covers:. The AI that drafts codebase PR templates also reads this field to suggest which pages are likely affected by a change.

covers:
  - pkg/logger
  - pkg/requestmiddleware

Each entry is a path relative to the codebase root, pointing to a package directory. No wildcards, no trailing slashes, no individual file paths.

Set covers: [] for pages that have no direct codebase counterpart: ADRs, architecture overviews, meta pages, index pages, and onboarding guides.

Malformed if: not a YAML array, any entry contains glob characters (*, ?, [, ]), or any entry has a trailing slash.

---

"Edited by" bar — derived, not stored

The bar at the bottom of each page (Edited by <author> · <date>) is computed from git history at build time, not from frontmatter:

• author — the git author of the last commit that touched the file. Because the repo squash-merges, this is the PR opener.
• date — when that commit landed on main (the squash/merge date).

There is nothing to fill in and no commit to stamp it: enabling showLastUpdateAuthor / showLastUpdateTime in docusaurus.config.ts is what populates it. See src/theme/DocItem/Footer/index.tsx for the rendering.

---

Docusaurus system fields

These are consumed by Docusaurus only. The bot ignores them.

Field	Type	When to use
sidebar_position	integer	Override alphabetical ordering within a category. Lower = higher.
sidebar_label	string	Override the title in the sidebar when the full title is too long.
slug	string	URL path override. Only used on docs/index.md (slug: /). Do not use elsewhere.

---

CI validation rules

A GitHub Actions workflow runs on every PR that touches docs/. It parses the frontmatter of every changed .md file and fails the check if any field is missing or invalid. The intent is to catch malformed pages before they reach main — a missing or empty description degrades bot output quality on every subsequent run.

A page is malformed if any of the following is true:

1. No frontmatter block present.
2. title is missing or an empty string.
3. description is longer than 160 characters or contains a newline.
4. covers is missing, not a YAML array, or any entry contains glob characters (*, ?, [, ]) or a trailing slash.
5. The page lives under docs/adr/ and title does not match ADR-\d{4}:.