MyST frontmatter schema

Built-in id: myst:frontmatter:1.10

Published at https://hawkeyexl.github.io/manni/schemas/myst/1.10.json. A $schema that names this URL resolves to the bundled copy, with no network call.

myst:frontmatter:1.10 checks the page-level frontmatter mystmd 1.10 reads from a .md page. It requires nothing, because MyST lifts a missing title from the first heading in the document. It is one of the platform schemas, which say what a generator accepts rather than what your team agreed.

Property	Value
Id	myst:frontmatter:1.10
Title	MyST page frontmatter v1.10
Files it fits	.md
Dialect	Draft 2020-12
Required fields	None
Additional properties	Allowed (additionalProperties: true)
Reference kind	builtin
On by default	No
Upstream reference	Frontmatter
JSON	myst/1.10.json

Use it

Name the id in manni.config.yaml:

manni.config.yaml

meta:
  schemas:
    - myst:frontmatter:1.10

For a one-off run, pass the id directly:

manni meta validate docs/ -s myst:frontmatter:1.10

A MyST tree that also carries reStructuredText pages splits the two by extension, as composing with a vocabulary shows.

Fields

The largest built-in, and the one whose value is mostly in its length caps. MyST silently truncates or rejects over-long values, so the caps are the constraint a real document trips.

Field	Cap
title, subtitle, description, label	500 characters
short_title, subject	40 characters

Beyond those, the schema types the identity and publication fields. Those are authors, editors, reviewers, affiliations, doi, arxiv, pmid, pmcid, license, open_access, venue, volume, issue and funding. It also types the source links github, edit_url, source_url and binder, and the execution blocks kernelspec and execute. pmcid is checked against PMC followed by digits.

Every field the schema describes, by type:

Field	Type	Notes
title, subtitle, description, label	string	At most 500 characters.
short_title, subject	string	At most 40 characters.
date, copyright, doi, arxiv, github, thumbnail, banner	string
keywords, tags	string or string array
authors, editors, reviewers	person or list of persons	A person is an object, or a string naming one declared elsewhere by id.
affiliations	object or array	Array entries are strings or objects.
license, venue	string or object
open_access	boolean
pmid	integer
pmcid	string	PMC followed by digits.
edit_url, source_url, binder	string	uri-reference.
first_page, last_page	string or number
volume, issue	string, number, or object
funding, exports, downloads	object or array
kernelspec, execute, math, abbreviations, numbering, parts, options	object

A person object types name, id, orcid, email, corresponding, roles, affiliations, equal_contributor, deceased, note and url.

Controlled vocabularies are checked for shape, not membership

MyST documents 14 CRediT contributor roles plus aliases. They are not transcribed into the schema, so roles is checked as a list of strings and nothing more. The same discipline applies to ms.topic and to Dublin Core’s type. A vocabulary is enumerated only where the published list is authoritative and complete. An enum assembled from examples rejects correct documents.

Additional properties

Project-level keys that belong in myst.yml rather than a page are not described, and pass as unknown keys. Those are bibliography, references, requirements and social.

Example page

A page carrying the common identity fields. This is test/fixtures/platform/myst-valid.md, and it passes.

docs/reproducible-builds.md

---
title: Reproducible builds
short_title: Builds
subtitle: A practical guide
description: Why a build that cannot be reproduced cannot be reviewed.
date: 2026-08-23
subject: Software engineering
license: CC-BY-4.0
open_access: true
keywords:
  - reproducibility
  - builds
tags:
  - guide
authors:
  - name: Ada Lovelace
    orcid: 0000-0002-1825-0097
    corresponding: true
    email: ada@example.org
---

A common mistake

A short_title is the abbreviated title for running headers and navigation, so it is capped at 40 characters:

test/fixtures/platform/myst-bad-short-title.md

---
title: A perfectly ordinary title
short_title: This short title is far too long to be a short title at all
---

✗ test/fixtures/platform/myst-bad-short-title.md
    /short_title  must NOT have more than 40 characters  (line 3)  [myst:frontmatter:1.10]

1 file checked, 0 passed, 1 failed, 1 error

Shorten it to 40 characters or fewer.