Content Frontmatter Reference

Overview

All content collections use Zod-validated frontmatter schemas. The authoritative field inventory is always the schema source file — this doc teaches the system model and field categories, not an exhaustive field list.

Who this is for

• Editors looking up which frontmatter fields are available for pages, articles, and docs
• Implementors checking field types, defaults, and validation rules
• Developers extending collection schemas or adding new fields

Collection	Schema location	Ownership
pages, articles	src/content.config.ts (contentSchema)	SITE-OWNED
theme-docs	defineDocsCollection() in src/core/config/theme-docs-collection.ts	CORE-OWNED
site-docs	defineDocsCollection() in src/site/config/site-docs.ts	SITE-OWNED
fragments	src/content.config.ts (inline)	SITE-OWNED

Both docs collections use the shared defineDocsCollection() factory from src/core/config/docs-collection-factory.ts (CORE-OWNED). The factory produces a validated Astro collection from parameters — each collection customizes topics, docId prefix, and extensions.

Pages & Articles (Shared Schema)

Pages and articles share a common contentSchema. Both collections accept the same fields. Fields fall into these categories:

Required fields

Every page and article must have title and description. These drive the <h1>, meta tags, and listing card text.

Content metadata

Optional fields for dates (datePublished, dateModified), authorship (author), and cross-references (relatedArticles). Dates accept ISO 8601 format and are coerced to Date objects at build time.

Taxonomy

Articles support two taxonomy axes: a single category (matched against the site config mapping table) and multiple freeform tags. Both generate listing pages under /articles/. See the Taxonomy section in Content Collections (DOC-00005) for the full taxonomy model.

SEO and visibility

Fields like draft, noindex, canonical, excludeFromSitemap, and excludeFromFeed control how content appears in builds, search engines, and feeds.

Display overrides

heroTitle overrides the rendered hero heading while title remains the SEO/tab title. shortTitle provides a compact label for navigation and breadcrumbs. contentWidth and sidebarPosition control layout. toc, tocStartLevel, tocEndLevel, and readingTime control per-page UI features. lightbox (boolean, optional) enables or disables the image lightbox for a specific page — when omitted, the collection default from site config applies (REQ-00049).

Representative example

---
title: Getting Started with Our Platform
description: A quick guide to setting up your first project.
datePublished: 2026-03-01
category: Development
tags:
  - onboarding
  - quickstart
heroTitle: Start Building Today
toc: true
---

Docs Collections (Via Schema Factory)

Docs collections are produced by defineDocsCollection(), which generates a base schema shared across all docs collections. Theme-docs extends this base with governance-specific fields via the factory’s additionalDocTypes, audience, and extend parameters. Site-docs uses the base schema without extensions. Key base additions beyond the shared content schema:

• docId (required) — immutable DOC-NNNNN identifier for cross-referencing
• topic (required) — groups docs for sidebar navigation. Valid keys are defined in each collection’s topic tuple (e.g., THEME_DOC_TOPICS, SITE_DOC_TOPICS).
• audience — required for theme-docs (editor, implementor, developer); optional for site-docs (omitted by default)
• docType (required) — base types: guide, reference, policy, how-to, tutorial, overview, topic-index. Theme-docs adds showcase and layout-recipe via the factory’s additionalDocTypes parameter.

Default overrides

Field	Docs Default	Shared Default	Reason
noindex	true (theme-docs) / false (site-docs)	false	Theme-docs are internal; site-docs are customer-facing
tocStartLevel	2	1	Docs start TOC at H2
tocEndLevel	3	2	Docs end TOC at H3

See the Documentation Guide (DOC-00001) for the full docs frontmatter contract and writing standards.

Fragments

Fragments are reusable content blocks embedded into pages. They use a minimal schema with a required fragmentId (stable reference key) and optional title, notes, and tags for editorial context and organization. Fragments are not routed — they have no URL.

See src/content.config.ts for the complete fragment schema.