Pages and Document Models

Document models validate the custom frontmatter fields on a page – the fields specific to your content type, like an event’s venue or a product’s price. How a page gets bound to a model depends partly on where it sits in the content tree, which is why it belongs in this chapter. This page covers the binding rules and the one constraint that trips people up; the Document Models guide covers authoring models in full.

What a model may govern

A model describes your custom fields only. The built-in fields that Accent parses itself are handled by the core page pipeline and must not appear in a model’s fields::

title, date, tags, author, template, status, menu, lead, published, relations, redirect, rewrite, publish_date, unpublish_date, and model.

These are not part of the data a model validates. Declaring one in a model has no effect – it is ignored, not enforced. Keep your fields: list to the custom frontmatter your templates actually read.

How a page binds to a model

A page is matched to a model in one of three ways, checked in this order:

1. Explicit model: field in the page’s frontmatter.
2. Template name that matches a model name.
3. A _model.yaml file in the page’s directory – or any ancestor up to the content root – containing model: <name>. This binds every page beneath it.

The third route is where content organization and models meet: dropping a _model.yaml in a directory binds the whole subtree, so the shape of your folders becomes the scope of your models. Put _model.yaml with model: event in content/events/ and every page under /events is validated as an event, with no per-page frontmatter.

content/
  events/
    _model.yaml          # model: event  -- binds everything below
    01.rust-conf.md      # validated as an event
    02.meetup.md         # validated as an event

Model names are filename stems

In all three cases the model name is the model file’s name without the .yaml extension (its filename stem), not the human-readable name: label inside the file. A model defined in models/event.yaml is referenced as event, whatever its name: says.

If a model: field or a _model.yaml references a name that is not loaded, the page is left unvalidated and a warning is logged – it is not an error, so a typo fails open rather than breaking the build.

See also

• Document Models – defining fields, types, constraints, inheritance, and validation modes.