Pages and Document Models

Document models validate a page’s frontmatter – both the fields specific to your content type, like an event’s venue, and the core fields Accent understands itself. 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; the Document Models guide covers authoring models in full.

What a model may govern

A model governs every frontmatter field on a page. The core fields – title, date, author, lead, tags, status, template, menu, and the rest – are declared by a built-in model named core that every model inherits automatically. Declaring one in your own fields: overrides the core declaration and is enforced:

# models/news.yaml
fields:
  date:
    type: date
    required: true      # a dateless news post now fails validation
  venue:
    type: string        # your own field, same rules

The single restriction is that a core field’s shape is fixed: title holds a string, tags holds a list. A model that declares title: { type: number } is refused at load time. Constraining a core field is always fine; reshaping one is not.

Earlier releases ignored core fields in fields: entirely – declaring date there did nothing. It now takes effect, so a model that already listed core fields may start reporting issues on legacy content. That is the fix working.

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.