Front Matter Standard

Summary

This standard defines required metadata, types, controlled values, and conditional fields for documentation pages.

Audience

• Documentation authors
• Documentation tooling maintainers

Reference Content

Every publishable page must begin with valid YAML front matter.

Schema

Field	Requirement	Format and use
id	Required	Stable, unique, lowercase kebab-case identifier.
title	Required	Human-readable page title.
description	Required	One-sentence search and preview description.
sidebar_label	Required	Concise navigation label.
slug	Conditional	Use only when the generated route must differ from the file path.
tags	Required	YAML list of approved classification tags.
keywords	Required	YAML list of useful discovery terms.
audience	Required	YAML list using controlled audience values.
owner	Required	Accountable team or role identifier.
reviewers	Required	YAML list of required reviewer roles or teams.
status	Required	Controlled lifecycle value.
visibility	Required	Controlled access classification.
content_type	Required	Controlled content classification.
source_type	Required	Controlled origin classification.
last_reviewed	Required after review	ISO 8601 date in YYYY-MM-DD format.
review_cycle	Required	monthly, quarterly, semiannual, annual, or event-driven.
related_docs	Required	YAML list of stable documentation paths; use an empty list when none exist.

Enterprise metadata extension

The enterprise metadata model extends this core schema with implementation state, ownership, dependency, relationship, versioning, and review fields. These fields are optional during phased migration of the existing documentation corpus, but the documentation validator checks their types and controlled values whenever they are present.

New module documentation should populate applicable enterprise fields before approval. Use empty relationship lists when no relationship has been confirmed; do not infer dependencies or ownership.

Example

---
id: page-identifier
title: "Page title"
description: "A concise description of the page."
sidebar_label: "Page label"
slug: /approved-custom-route
tags:
  - approved-tag
keywords:
  - discovery-term
audience:
  - developer
owner: accountable-team
reviewers:
  - subject-matter-expert
status: draft
visibility: internal
content_type: how-to
source_type: authored
last_reviewed: 2026-07-14
review_cycle: annual
related_docs: []
---

Omit slug when the default file-derived route is correct.

Controlled values

status

• planned
• draft
• in-review
• approved
• deprecated
• archived

visibility

• public
• partner
• customer
• internal
• restricted
• confidential

restricted is the canonical classification for material requiring explicit access control. The legacy confidential value remains accepted during metadata migration and maps to the same handling policy.

content_type

• overview
• concept
• how-to
• tutorial
• reference
• troubleshooting
• runbook
• release-note
• adr
• generated-reference

source_type

• authored
• generated
• hybrid

Approved audience values

• business-user
• employee
• manager
• hr-admin
• payroll-admin
• recruiter
• platform-admin
• customer-admin
• implementation-partner
• support-engineer
• developer
• qa-engineer
• devops-engineer
• solution-architect
• product-owner
• security-engineer

Metadata values must describe the page, not assumed product capabilities.

Related Articles

• Page structure
• Validation tooling
• Enterprise metadata model

See Also

• Naming conventions

Keywords

• Front matter
• Metadata schema
• Controlled values

Revision Information

• Last reviewed: 2026-07-14
• Owner: documentation-team
• Status: Approved