Page Frontmatter Reference

Frontmatter is YAML metadata at the top of each markdown file, enclosed in --- delimiters. Pagesmith uses frontmatter for page titles, descriptions, ordering, draft status, and feature-specific fields like hero sections and blog metadata.

Notice docs schemas keep most fields optional with passthrough extras, while collection schemas enforce the required fields called out in the tables below.

Frontmatter Format

Frontmatter is written in YAML at the very beginning of a markdown file:

1---2title: Getting Started3description: Learn how to set up your first Pagesmith project4order: 15---67# Getting Started89Your content here...

Field Reference

Docs Frontmatter (DocsFrontmatterSchema)

These fields are recognized by @pagesmith/docs for documentation sites. The schema uses .passthrough(), so additional custom fields are preserved and available in layouts.

Hero Object Fields

When using the home layout, the hero object supports:

Features Array Fields

Each entry in the features array supports:

Chrome Object Fields

Control which parts of the page chrome are visible:

Packages Array Fields

Each entry in the packages array supports:

Code Example Object Fields

Base Frontmatter (BaseFrontmatterSchema)

These fields are defined in @pagesmith/core and are available when using the content layer directly with defineCollection. They form the foundation for blog and project schemas.

Blog Frontmatter (BlogFrontmatterSchema)

Extends BaseFrontmatterSchema with blog-specific fields. Use this schema when defining a blog collection with defineCollection.

Project Frontmatter (ProjectFrontmatterSchema)

Extends BaseFrontmatterSchema with project-specific fields. Use this schema for portfolio or project showcase collections.

Common Patterns

Minimal Docs Page

The simplest frontmatter for a documentation page — just a title:

1---2title: Installation3---

When even the title is omitted, Pagesmith generates one from the file’s directory name using title-case conversion (e.g. getting-started becomes “Getting Started”).

Docs Page with Navigation Labels

Override sidebar and nav labels independently from the page title:

1---2title: Configuration Reference for pagesmith.config.json53navLabel: Configuration4sidebarLabel: Config Reference5description: Complete guide to all configuration options6---

Draft Page

Keep a page in your content directory without publishing it:

1---2title: Upcoming Feature3description: Documentation for a feature still in development4draft: true5---

Home Page with Hero and Features

The home page layout reads hero and features from frontmatter (or from home.json5 if not present in frontmatter):

1---2title: My Project3description: A modern toolkit for building content sites4hero:5  name: My Project6  text: Build content-driven sites7  tagline: Zero configuration, maximum output8  actions:9    - text: Get Started10      link: /guide/getting-started11      theme: brand12    - text: View on GitHub13      link: https://github.com/my-org/my-project14      theme: alt15features:16  - title: Fast Builds17    details: Parallel page processing and incremental dev server18  - title: Full-Text Search19    details: Built-in Pagefind integration with zero configuration20  - title: Type-Safe Content21    details: Zod schema validation for all frontmatter and data22---

Blog Post

Using BlogFrontmatterSchema in a custom collection:

1---2title: Announcing v1.03description: Our first stable release is here4publishedDate: 2026-03-015tags:6  - release7  - announcement8category: releases9featured: true10coverImage: ./cover.png11---

Project Entry

Using ProjectFrontmatterSchema in a portfolio collection:

1---2title: Pagesmith3description: A filesystem-first content toolkit4publishedDate: 2025-06-015tags:6  - tooling7  - static-site8gitRepo: https://github.com/user/pagesmith9links:10  - url: https://pagesmith.dev11    text: Documentation12  - url: https://pagesmith.dev/guide/getting-started13    text: Quick Start14---

Schema Usage in Collections

The base, blog, and project schemas are exported from @pagesmith/core for use with defineCollection:

1import {2  defineCollection,3  defineConfig,4  BaseFrontmatterSchema,5  BlogFrontmatterSchema,6  ProjectFrontmatterSchema,7} from "@pagesmith/core";89const posts = defineCollection({10  loader: "markdown",11  directory: "content/posts",12  schema: BlogFrontmatterSchema,13});1415const projects = defineCollection({16  loader: "markdown",17  directory: "content/projects",18  schema: ProjectFrontmatterSchema,19});2021export default defineConfig({22  collections: { posts, projects },23});

For docs sites using @pagesmith/docs, the DocsFrontmatterSchema is applied automatically to all content pages. You do not need to configure it manually.

Validation Rules

Frontmatter validation happens at different stages depending on the package:

@pagesmith/docs validation

The docs package applies DocsFrontmatterSchema automatically to all content pages. Key rules:

• All fields are optional. If title is omitted, it is auto-generated from the content slug using title-case conversion.
• Unknown fields are preserved via .passthrough().
• order must be a number if present. String values like "first" will fail validation.
• draft: true pages are excluded from build, navigation, search, and sitemap.

@pagesmith/core validation

When using defineCollection with a custom Zod schema, validation rules depend on your schema:

• Required fields cause build errors if missing from frontmatter.
• Type coercion works for z.coerce.date() (accepts date strings) and z.coerce.number().
• Default values from z.default() are applied when the field is missing.
• Strict schemas (without .passthrough()) reject unknown frontmatter fields.

Content validators (additional checks)

After schema validation, content validators run on the parsed MDAST:

Disable built-in validators per collection with disableBuiltinValidators: true.

Custom Fields

Both DocsFrontmatterSchema and BaseFrontmatterSchema use .passthrough(), which means any additional YAML fields you add to frontmatter are preserved in the page’s frontmatter object. Custom layouts can access these fields:

1---2title: API Reference3description: Full API documentation4customBadge: beta5showToc: false6---

These custom fields are available as page.frontmatter.customBadge and page.frontmatter.showToc in layout components. No schema changes are needed.