Frontmatter
Every front matter key a site page and a folder can set in Pattern Dump: the grammar, the keys for the build, layout keys, childLayout and childDefaults.
---
title: Hello, articles
layout: article
date: 2026-11-14
tags: [getting-started, notes]
categories: [notes]
draft: false
---
A site page's frontmatter is the block between the two --- lines at the top of its markdown file. Other tools call it front matter. Some of its keys are for the build and never reach the layout. A few are filled by Pattern Dump. Everything else is data for the page's layout, which must declare it. Sites explains why.
A problem is shown as <file>:<line>: <message>, the file relative to the pages folder and without a line when there is none, and it fails the page.
Grammar
The frontmatter is a fixed grammar, not YAML:
key: valueon a line;- a list inline,
[a, b], or one item per line under the key,- a; - one level of keys under a key, each indented the same as the first.
Every value is text until the layout's schema gives it a type, and quotes around a value are removed. childDefaults: is the one key read a level deeper: a page's frontmatter, written under it. A byte order mark and CRLF line endings are read as clean input.
A key written twice takes its last value, and is still a problem on a site page. The other problems, each with its line:
- A block that is never closed
the frontmatter block opened here is never closed: end it with a line holding only ---- A key written twice
duplicate key "<k>"- A line that is no key, value or list item
cannot read this line: <line>- A list item with no key above it
list item with no key above it: a list follows a line `key:`- Keys under a key, indented unevenly or deeper than one level
nested value: one level of keys under "<k>", each indented the same as the first- An inline list without its closing bracket
"<k>": the list opened with [ is never closed with ]- A value with an opening quote and no closing one
"<k>": the value has an opening quote with no closing one- A line ending in a carriage return alone
line ends in a bare CR: use LF or CRLF line endings
Keys for the build
Fourteen keys belong to the build and are never passed to the layout: layout, childLayout, order, redirectFrom, index, image, date, updated, tags, categories, draft, sort, view and toc. A layout schema that declares one fails every page that uses it: layout "<name>" declares "<key>", which a page sets for the build, not for its layout: rename it in the layout's schema. nav is checked with them. The build keys are checked even when the layout doesn't exist.
layout- One layout name. Default: the
childLayoutorchildDefaults.layoutof the nearest folder above that sets one, elsepage. - A list:
layout must be one layout name, not a list. A name that is no layout, such as a partial, a variant or a path:layout "<x>" is not a layout: the layouts are "a", "b", …, or, with none at all,… is not a layout: the project has no layouts (components in a layouts/ folder of its patterns, or page and template patterns marked with x-pd-layout). A schema that can't be read:the schema of layout "<x>" cannot be read: <error>. navtrueorfalse.falseleaves the page out of the navigation, of its folder'schildrenand ofprevandnext; it still renders, is searchable, and is in the sitemap andllms.txt. On a folder'sindex.md, it leaves out the folder with its pages. Any other value:nav must be true or false. A layout still getsnav, the navigation.order- A number that ranks a page or folder among its siblings, lower first. Default: 0. Ties go by list position, then by name. On a folder's
index.md, a list (or text with commas) orders the folder's pages by name, with...where the others go, else last; a child's own number wins over the list. The rootindex.mdis both Home and the top level's list, where Home is namedindex. Not checked on site pages: a value that isn't a number is read as a list. redirectFrom- One old route or a list, each forwarding to this page. A route starts and ends with
/, with no query, fragment, whitespace,.or..segment. Else:redirectFrom: "<r>" is not a route: each old route starts and ends with "/", such as "/old/page/", with no query or fragment, and with several,redirectFrom: "<r1>", "<r2>" are not a route: …. indextrueorfalse.falsegives the page<meta name="robots" content="noindex">, leaves it out of the sitemap and keeps it out of the search index. Any other value:index must be true or false.image- The page's image for link previews: a path to a file in the assets, such as
/assets/images/share.png, elseimage must be a path to a file in the assets, such as "/assets/images/share.png". The file must exist (image "<p>" does not exist in the assets) and be a PNG, JPEG, GIF or WebP by its bytes:image "<p>" is an SVG; link previews need a raster image (PNG, JPEG, GIF or WebP),image "<p>" is not a PNG, JPEG, GIF or WebP image (read from its bytes, whatever its name). date- A real date,
YYYY-MM-DD. Else:date "<v>" is not a date: write it YYYY-MM-DD, such as "2026-11-14". A date after today holds the page back frompd build(see Drafts and scheduled pages). updated- A date, not before
date:updated <u> is before the page's date, <d>: a page is updated after it is published. tags- One value or a list. Without
site.tagsin the config, each is lowercase letters, digits and hyphens (tags: "<t>" is not a tag: a tag is lowercase letters, digits and hyphens, such as "design-systems") and none twice (tags: "<t>" is listed twice). Withsite.tags, each is a declared key or an old key. categories- One value or a list of declared keys or old keys from
site.categories. - For both: an unknown value,
categories: "x" is not a category: did you mean "<x>"?, elsethe categories are "a", "b" (site.categories), elsethe site declares none (site.categories in the config); several problems follow one prefix, joined with;. An old key builds as the key it now is, withwarning: <place>: <kind> "<old>" is now "<new>" (renamed in site.<kinds>): write "<new>", and beside its own key it is"<key>" is listed twice ("<old>" is its old key). drafttrueorfalse, elsedraft must be true or false.truekeeps the page out ofpd build.toctrueorfalse, elsetoc must be true or false.sort,view,childLayout- Only on a folder's
index.md, the root's included, elsesort orders a folder's pages, so it belongs on the folder's index.md, not on a page,view names how a folder's pages are listed, so it belongs on the folder's index.md, not on a pageandchildLayout sets the layout of a folder's pages, so it belongs on the folder's index.md, not on a page.sortisorder(the default) ordate, newest first;viewandchildLayouttake one name. Collections and queries hassortandview.
There is no slug, permalink or url key: a page's route comes from its file path only. Such a key is an ordinary layout key.
Keys Pattern Dump fills
body, site and page are filled by Pattern Dump, and a page that sets one gets "<key>" is filled by Pattern Dump, not by a page. A required in the layout's schema that names one is satisfied. The body slot that a layout's x-pd-content names is filled too: "<slot>" is filled by Pattern Dump with the page's markdown (x-pd-content of layout "<n>"), not by a page.
The keys that name the layout's queries are the build's as well, and go to the query. Collections and queries has their options.
Layout keys
Every other key must be declared in the properties of the layout's schema. title and description are no exception.
- An undeclared key
"<key>" is not declared by layout "<name>", with: did you mean "<x>"?when a declared, reserved or query key is close. A layout with no schema declares nothing:"<key>" is not declared by layout "<name>", which has no schema. Nothing is read from the layout's sample data.- A required key missing
"<key>" is required by layout "<name>".- A value of the wrong type
- A value is turned into the declared type: a
number(-?\d+(\.\d+)?), aninteger(-?\d+), aboolean(trueorfalse), anarray(its items checked byitems.typeorenum), astring(a list is refused). A type union tries each type in order, andenumis checked after. The messages:"<k>" must be a number (got "x"),must be a whole number (got …),must be true or false (got …),must be a list (got "x"),has an item that …,must be one of "a", "b" (got "x"),must be text, not a list. - A key declared as
objectornullcan't be set:"<k>" has a type (object) a page cannot set in frontmatter. A key declared with notypetakes the value as written, text or a list. A value that fails its check is left out of what the layout gets. - Keys indented under another key
- Only a query of the layout takes them:
"<key>" has keys indented under it, which only a query of the layout takes: write its value on the line.
When the page takes its layout from a folder, each message names it: layout "<x>" (the childLayout of <index.md>).
Folders
A folder's index.md is the folder's own page, and a page of the folder above it: it takes its layout and defaults from the folders above, not from its own childLayout or childDefaults.
childLayout- The layout of every page under the folder that names none, at any depth; the nearest folder that sets one wins, and a page's own
layoutwins over all. A name that is no layout fails theindex.mdat its line,childLayout "<x>" is not a layout: …, and each page that takes it:<page>: layout "<x>" (the childLayout of <index.md>) is not a layout: …. childDefaults- Frontmatter for every page under the folder, at any depth, written as a page writes it.
childDefaults.layoutbesidechildLayoutis a problem:childDefaults.layout and childLayout both set the layout of this folder's pages: keep one.
Defaults apply key by key: the page's own value wins, else the nearest folder that sets the key. A query's options apply option by option, and options from different folders merge. A list is replaced, never joined: a folder's tags: [guide] and a page's tags: [setup] give [setup]. A page that writes a plain value where the folder gives a query's options keeps its plain value.
Some keys can't be defaulted, since they are one page's own or belong to a folder's own index.md: title, order, redirectFrom, date, updated, sort, view, childLayout, childDefaults, body, site and page. Each is a problem on the index.md at its line, childDefaults.<k>: "<k>" can't be set for a folder's pages (…): set it on each page, and never reaches a page. nav can be defaulted; on the index.md itself it applies to the folder's pages, and a page's own nav: true wins.
The index.md checks the build keys it gives (tags, categories, draft, index, toc, image) and layout once, so a folder without pages is checked too, with messages that start childDefaults., such as childDefaults.toc must be true or false. On each page, a default is checked against that page's layout, and a problem names where it came from: <page> (from the childDefaults of <index.md>, line <n>): <message>.
The 404 page and the generated tag and category pages take no folder defaults and no childLayout.
Drafts and scheduled pages
draft: truepd devshows the page and notes once,<path> is a draft: pd build leaves it out.pd buildreads the pages folder as if the file weren't there, and reports[pd build] drafts: <n> left out (<paths>). On a folder'sindex.md, it takes every page under the folder out ofpd build; inpd devthose pages are not drafts themselves. FromchildDefaults, it counts as each page's own, andpd buildprints per folder[pd build] <n> pages are drafts via the childDefaults of <index.md>.- A
dateafter today - The page is scheduled:
pd devnotes<path> is scheduled for <date>: pd build leaves it out until then, andpd buildholds it back, with every page under a folder whoseindex.mdis so dated, until the latest of the dates, and reports[pd build] scheduled: <n> held back (<path> until <date>, …). Today is the build machine's date in UTC, taken once per build. A draft is never scheduled.
Since drafts and scheduled pages are left out of pd build, a navigation entry that names one fails the build: site.globals.navigations.<name>[i]: "<path>" is not a page in the pages folder.