Front matter reference

Inkan reads metadata from YAML front matter and from two small YAML files. All of it is validated when the site is built, so a wrong value fails inkan build with the file name and the field. Fields that are not listed here are ignored.

Records and pages in the content folder#

Every .md or .mdx file under contentDir accepts these fields. Records (files in a type folder) use all of them; plain pages mostly need title, description and order.

Values inferred from git are marked “From git history” on the record page and are not written back to the file; records fetched from a repo source and files in shallow clones keep no date or author. Turn the behaviour off with git: { dates: false, authors: false } in the config. See Fill date and authors from git.

Record paths are the path of the file inside the content folder without the extension. They work across projects. Relative Markdown links in the body ([see](../rfc/0001-x.md)) are another way to link records; see Link records by path.

The type and number are not front matter: they come from the folder (adr, rfc, or a key you added to docTypes) and from the leading digits of the file name. sre/adr/0007-foo.md has number 7 and the reference SRE-ADR-0007. See Record type comes from the folder.

Custom keys#

Keys declared under fields in the config or in a _project.yml are also front matter keys: risk: high, cost: 40, pci: true. They are checked against their type and an invalid value or a missing required field fails the build. Any other unknown key is still ignored. A field cannot be named like a built-in key from the table above. See Custom metadata fields.

Full example#

1
---
2
title: "Use Stripe as the primary payment provider"
3
description: Stripe covers every market we sell in and its API fits our ledger model.
4
status: accepted
5
date: 2026-01-18
6
authors: [jules, noor]
7
deciders: [sam]
8
tags: [payments, vendor]
9
supersedes: [payments/adr/0001-build-our-own-card-gateway]
10
supersededBy: []
11
related: [dbre/adr/0001-standardize-on-postgresql-16]
12
reviewBy: 2026-11-15
13
reviewers:
14
  noor: approved
15
  sam:
16
    state: changes-requested
17
    date: 2026-11-02
18
    note: Needs a rollback plan
19
reviewEvery: 1 year
20
comments: false
21
discussion: https://github.com/acme/decisions/discussions/42
22
draft: false
23
---

On this accepted record reviewBy is the next review; once inkan reviewed writes a reviewed date on or after it, the record comes back every year from that date.

Plain page example#

1
---
2
title: On-call guide
3
description: What to do when you are paged.
4
order: 10
5
---

The same three fields, title, description and draft, apply to Markdown and MDX files in pagesDir. order has no effect there because those pages are not in the sidebar.

More on the fields and the reasoning behind them: Metadata in front matter, Configurable status lifecycle.

Projects: _project.yml#

One _project.yml (or _project.yaml) per top-level folder gives the project a name on the site. The folder name is the project id used in URLs, record paths and the project filter.

1
name: "SRE"
2
description: "Reliability, on-call and the numbers we promise."
3
icon: activity
4
ink: c
5
motif: rings
6
owners: [marek, ania]
7
reviewEvery: 1 year
8
order: 10
9
links:
10
  - label: Runbooks
11
    url: https://runbooks.acme.dev

A folder without _project.yml is still a project; it is shown by its folder name and takes part in the ink and motif assignment like any other. See One folder per project and Generated record covers.

Authors: _authors.yml#

An optional list at <contentDir>/_authors.yml. Each entry’s id is the handle used in authors, deciders and owners. Handles that are not listed still work and are shown as written.

1
- id: ania
2
  name: "Ania Kowal"
3
  team: sre
4
  github: aniak
5
- id: jules
6
  name: "Jules Marchand"
7
  team: payments
8
  avatar: https://avatars.example.com/jules.png

See Optional author directory.

Landing extra: _landing.md#

<contentDir>/_landing.md (or _landing.mdx) is rendered in the content section of the home page. Its front matter is not validated and not used; the body is what counts. See Landing page from config.

Validation#

• title and name are required; everything else is optional.
• status must be a key of statuses in the config. When you replace that map, old values fail until you update them.
• reviewers entries must be handles with a state of pending, approved or changes-requested.
• date, reviewBy and reviewed must be dates. Unquoted 2026-01-18 is a YAML date and works; so does the same text in quotes.
• reviewEvery, on a record or in _project.yml, must be an interval (1 year, 6 months, 90 days, 2 weeks, or the short forms 1y, 6m, 90d, 2w) or never / false.
• List fields accept a single value or a list.
• links[].url in _project.yml must be absolute or start with /.
• Custom fields must match their declared type; a field with required: true must have a value. fields in _project.yml must be valid field definitions, and one field name may not have two types across projects.

A failed check stops inkan build and names the file and field. The dev server reports the same error when it loads the file. Details: Validate config and content at build time.