Many posts about frontmatter for AI promise that richer metadata makes agents answer better. The evidence is thin. When Kinde added fields such as audience, complexity, keywords and ai-summary across its docs, its AI search vendor, Inkeep, told the team that “the AI agent we use won’t benefit too much from the extra front matter because they analyse our pages in detail already” (Front up with front matter, Alex Norman, 31 July 2025). That pipeline reads the page itself.
We think the better reason to care about frontmatter is governance. Metadata lets you find content that is no longer true and fence it off before a human or an agent follows it. That only works if the metadata is there and correct, which is why the real subject here is frontmatter validation in CI.
What frontmatter is actually good for
Every page should answer four questions in machine-readable form:
- What type of page is this?
- Is it current?
- Which version does it apply to?
- Who owns it?
With those answered, your docs become queryable like data. One search across the repo lists every deprecated page, every page for a version you no longer support, and every page with no owner. A deprecated page that says so in its documentation metadata can get a banner for human readers, be excluded or down-ranked by your search or AI pipeline, and point to its replacement. Deprecated documentation that doesn’t say so looks exactly like current documentation.
The OKF baseline
We’ve explained the Open Knowledge Format in our OKF explainer for documentation leaders, so here is only what matters for validation. The OKF specification, version 0.2, says “type is the only always-required key; a concept carrying just type is fully conformant”. title and description are recommended. The spec lists “Is it the current version? (lifecycle)” among the questions a consumer needs answered, and offers an optional status field (draft, stable or deprecated) plus stale_after, an instant after which the content counts as stale.
The sharp detail is this line: “Absent status ⇒ stable”. To any consumer following the spec, a deprecated page with no label is current. Labelling therefore has to be enforced, not encouraged.
OKF is also open to extension: consumers “MUST NOT reject documents with unrecognized fields”. A project-specific version key is fine.
Labelling versions and deprecations
Pick one lifecycle vocabulary per docset and don’t mix them. Either use OKF’s status, or use the lifecycle vocabulary from manni (the validation tool covered below), whose lifecycle field takes draft, published, deprecated or archived.
The manni vocabulary adds a rule we like: a page marked deprecated must also carry replaced-by or remove-by, because “A deprecated page must say what comes next: the replacement, or the removal date, or both.” That turns “deprecated” from a shrug into a pointer.
For pages that apply to a specific release, add a version field of your own. For ownership, manni’s stewardship vocabulary covers owner, last-reviewed and review-interval, among other fields. An illustrative page:
---
type: How-to
title: "Rotate an API key"
description: Replace an active API key without downtime.
lifecycle: deprecated
replaced-by: /guides/api-keys/rotate-v3
version: "2.x"
owner: platform-docs
---This sits alongside whatever versioned-docs features your site generator already has; it labels the pages rather than replacing that mechanism. Treat it as part of your docs lifecycle, not a one-off clean-up.
How to check it
manni is an open-source CLI (MIT licence, Node.js 24 or later), previously published as docmeta. Its manni meta command “validates the presence and format of document metadata against JSON Schema, built for CI”. It does not judge prose quality. Its built-in schemas cover OKF, Diátaxis and The Good Docs Project, plus the frontmatter contracts of site generators such as Docusaurus, Hugo, Jekyll and MkDocs Material.
With no configuration it validates against a default set of eleven built-in schemas, in which the OKF schema requires type and manni’s core vocabulary requires title and description. Forward this to an engineer:
npx @hawkeyexl/manni meta validate "docs/**/*.md"A clean run exits 0, validation failures exit 1 (which is what fails the CI job), and operational errors exit 2. The project publishes a GitHub Action with inline pull request annotations and a pre-commit hook. For where this fits among your other pipeline checks, see five CI workflows for documentation.
One detail matters. The README notes that the other manni vocabularies, lifecycle included, “check a field only when a page carries it”. The default run catches a deprecated page with no replaced-by, but it won’t force every page to declare a lifecycle or a version. To make those fields required in your YAML frontmatter, register a small schema of your own: meta.register in manni.config.yaml loads local JSON schemas, each “named by its $id, which then works anywhere a built-in id does”.
Backfilling an existing docset
The usual objection is “we have hundreds of pages and none of them have this”. manni meta fill “infers the metadata properties your schema asks for but a page does not carry”, using an LLM provider it detects (an Anthropic or OpenAI API key, a signed-in claude CLI, or a local model). It only writes values at or above --confidence (default 0.7); values below it “are skipped and reported by name” and are never written.
Run it with --dry-run first. Because fill writes in place by default, the manni README advises running it “on a clean tree” and reviewing the diff.
Our view on what to accept: an inferred description or type is fine to take in bulk after a skim. A lifecycle: deprecated or a version label should be a human decision, because that is exactly the claim you are trying to make trustworthy. Use the tool to clear the backlog, then have owners confirm the status fields.
None of this replaces writing for both audiences, a theme we cover in writing docs for humans and AI agents. It makes sure both audiences can tell which pages still hold.
Get the full checklist
This guide covers two of the 16 checks in our agent-ready docs checklist: “Consistent frontmatter” (UNDERSTAND layer, priority Optimise) and “Versions are labelled” (TRUST layer, priority Important). The baseline fields are a nice-to-have; the lifecycle and version labels are the part to do first. Get the free checklist.