Front matter

the settings at the top of every page

Contents

1Fields
2Validation
3Example
4References

Front matter is TOML between two +++ lines at the top of a page, before its markdown.^[1] What a page is for and how it is laid out is described on Pages, and the fields of an infobox on Infobox fields.

Fields

Field	Type	Default	Meaning
`title`	string	required	the page's name, at its top and in the sidebar^[2]
`intent`	string	required	what the thing is for, at most `budget.intent` words^[3]
`subtitle`	string	empty	a line under the title^[4]
`status`	string	`"draft"`	`"approved"` approves the page; any other value leaves it a draft^[5]
`goals`	true or false	true	`false` keeps the intent off the goals page and excuses the page from the checks that its sentences and infobox rows cite^[6]
`audience`	string	`"internal"`	`"user"` puts the page in the build `wiki user` makes^[7]
`categories`	list of strings	none	the categories named at the page's foot^[8]
`hatnote`	string	empty	a note shown above the page's text^[4]
`image`	string	none	a picture recorded in `PICTURES.toml`, shown at the top of the infobox^[9]
`image_caption`	string	empty	the caption under that picture^[9]
`infobox`	list of tables, written `[[infobox]]`	none	the infobox's groups, in the order written^[10]

Any other field is ignored, except kicker, which is refused.^[2]

Validation

Every problem below stops the build, and names the page's file.^[11]

Condition	Message
the page does not open with `+++`^[11]	`wiki: refunds.md does not open with a +++ front-matter fence`
the front matter never closes	`wiki: refunds.md never closes its +++ front-matter fence`^[1]
the TOML cannot be read	`wiki: refunds.md has unreadable front matter:` and the parser's error^[1]
`title` or `intent` is missing or empty	`wiki: refunds.md has no intent; every page must say what it is for`, naming `title` instead when that is the one missing^[12]
the intent is over its budget	`wiki: refunds.md's intent runs to 130 words, over the 120 an intent may use; say what the system is for, not how it works`^[12]
the page gives `kicker`	`wiki: refunds.md gives its subtitle as kicker, which is now called subtitle; rename kicker to subtitle`^[12]
`audience` is not `"internal"` or `"user"`	`wiki: refunds.md gives its audience as 'reader'; an audience is "internal" or "user"`^[12]
`image` names a picture with no record	`wiki: refunds.md shows flow.svg, which has no entry in PICTURES.toml`^[9]

Example

The front matter of an approved page marked for users, with its fences:^[1]

+++
title = "Refunds"
subtitle = "money back for a wrong charge"
status = "approved"
audience = "user"
categories = ["Payments"]
intent = """
Refunds exist so that a customer who was charged wrongly gets their money back without asking twice.
"""
+++

References

src/builder/build.py — read_front_matter() reads TOML between an opening +++ line and the next, and raises the first three messages.
src/builder/build.py — read_pages() reads title, intent, subtitle, hatnote, audience with its default "internal", status with its default "draft" and categories, and refuses kicker; goals_order(), uncited_problems() and infobox_problems() read goals; render_infobox() reads image, image_caption and infobox.
src/builder/config.py — read_config() reads budget.intent from wiki.toml, 120 words when it is absent; read_pages() in src/builder/build.py refuses an intent longer than that.
src/builder/build.py — read_pages() leaves subtitle and hatnote empty when absent, and render_page() fills template.html with the subtitle under the title and the hatnote above the text.
src/builder/build.py — write_site() renders a page as a draft when its status is anything but "approved".
src/builder/build.py — goals_order() leaves out a page whose goals is false, and uncited_problems() and infobox_problems() skip it; each reads an absent goals as true.
src/builder/build.py — write_site() renders only the pages visible_to() its audience, which in a user build are those whose audience is "user"; run() in src/builder/cli.py builds for users on wiki user.
src/builder/build.py — read_pages() reads no categories when categories is absent, and render_categories() names them in the bar template.html puts after the page's text.
src/builder/build.py — render_infobox() shows image at the top of the infobox with image_caption, empty when absent, under it, and raises the message for a picture with no entry in PICTURES.toml.
src/builder/build.py — render_infobox() shows the infobox groups in the order written, and none when it is absent.
src/builder/build.py — read_front_matter(), read_pages() and render_infobox() raise WikiError, which main() in src/builder/cli.py prints.
src/builder/build.py — read_pages() raises the messages for a missing or empty title or intent, an intent over its budget, kicker, and an audience outside AUDIENCES.

Last updated 14 September 2026Last audited never482 wordsabout 2 minutes to read12 sources cited0 claims with no source