Frontmatter

A page’s metadata is a Typst binding, not a header in another language:

#let frontmatter = (
  title: "Hello",
  date: datetime(year: 2026, month: 7, day: 9),
  tags: ("intro",),
)

The build reads that one top-level frontmatter export from the evaluated module. Because Typst evaluates it, the value is an ordinary dict: it can be computed from sys.inputs, from a loaded data file, or from anything else in scope.

A markdown page declares the same keys in a fenced block instead, in YAML, TOML or KDL. Every key on this page behaves identically there: the block is read into the same dict, and everything below is the same walk.

Recognized keys

Values are typed. A key with the wrong type stops the build with a diagnostic naming the file and the field, never a silent drop. The three dates take either a Typst datetime or a string spelled exactly YYYY-MM-DD, so a day needs no datetime(..) call:

date: "2026-08-05",

lang and translation only matter once a languages block exists; see multiple languages. redirect is covered on redirects.

description, summary, image, alt and author drive meta and social tags, the feeds, and what a listing row carries:

#let frontmatter = (
  title: "A post",
  description: "A short summary for search and social cards.",
  image: "cover.png",
  alt: "The cover, described for a reader who cannot see it",
)

They read the same in a listing, as entry.description, entry.image, entry.alt and entry.author, so a card component draws the very image the og:image tag names.

Naming a URL outright

path publishes a page where you say, whatever its collection’s permalink pattern would have produced:

#let frontmatter = (
  title: "About",
  path: "/about-us/",
)

Leading and trailing slashes are optional, so about-us is the same URL. A path whose last segment carries an extension names a file and publishes as one, which is what a site arriving from Jekyll needs:

It is the migration escape hatch: copy each old URL onto the page that answers it and the URL set matches by construction, with no permalink archaeology. Two pages claiming one path is an error naming both files, not a race.

path does not touch the page’s identity. Translations still pair on collection/slug, so each edition may state its own path and stay the same page in another language; an edition that states none publishes under its language prefix as usual.

Taxonomy keys

Any key declared under content { taxonomies } is recognized too, and collects a list of terms:

#let frontmatter = (
  title: "On Typst",
  tags: ("typst", "tooling"),
)

With taxonomies { tags } configured, this page is grouped under both terms. See taxonomies.

Opting out

The site decides whether a sitemap, a feed, a search index, a social card or a PDF is generated at all. A page decides whether it is in them:

#let frontmatter = (
  title: "Thanks for subscribing",
  exclude: ("sitemap", "search"),
)

A name outside that list fails the build rather than being ignored.

Everything else

Unknown keys aren’t errors. They pass through as extra frontmatter, yours to read in a template as page.frontmatter.<key> and in a listing as entry.extra.<key>.

Schemas

Free-form keys are easy to get wrong: a template reading a hero that a page never set renders an empty hole and the build stays green. A collection can say what its members must carry:

content {
  collections {
    blog {
      schema {
        title "str"
        tags "list"
        hero "str" optional=#true
        author
      }
    }
  }
}

Declaring a field requires it. optional=#true lets it be absent. A field with no type (author above) is required but unconstrained. A page that breaks the schema fails the build, pointing at the line in its frontmatter:

  × frontmatter `hero` must be a string, but is of type `integer`
   ╭─[content/blog/post.typ:3:9]
 2 │   title: "Hello",
 3 │   hero: 3,
   ·         ┬
   ·         ╰── not the declared type
   ╰────
  help: write it as `hero: ".."`, or change the `blog` collection's schema

The types are the Typst ones a frontmatter dict can hold, not a second type system:

A list says what it holds, so the parameter nests as deep as the data does:

schema {
  widths "list<int>"
  matrix "list<list<int>>"
  editor "dict" {
    name "str"
    email "str" optional=#true
  }
  reviewers "list<dict>" {
    name "str"
  }
}

A block declares the fields of the dictionary the type ends in, through however many lists wrap it. Nested fields are checked the same way, and are required unless they say optional=#true themselves. The diagnostic names the one that broke, down to the element:

  × frontmatter `reviewers.1.name` must be a string, but is of type `integer`

Values, not just shapes

A type says what a field is. Three keys beside it say what it may hold.

schema {
  status "one-of<draft|review|published>" default="draft"
  weight "int" min=1 max=10
  title "str" min=2 max=80
  tags "list" max=5 pattern="^[a-z][a-z0-9-]*$"
}

A pattern holds the string itself, or every element of a list of them, so the fault names the element that broke (tags.2). It is unanchored, as a regular expression is: write ^..$ to hold the whole of the value rather than a part of it. A pattern that does not compile is refused where it is written.

one-of is part of the type language rather than a key, so it composes like every other type: list<one-of<draft|published>> is a list of them, and a dict field can hold one.

A value of the right type that a field refuses anyway says so as a value:

  × frontmatter `status` must be one of "draft", "review", "published"
   ╭─[content/blog/post.typ:3:11]
 3 │   status: "reviewed",
   ·           ─────┬────
   ·                ╰── not what the schema allows
   ╰────

A default is what the page would have written, and lands where that would have: page.frontmatter.status reads "draft" on a page that declared none, and every listing, feed and card sees it too. What the page wrote always wins.

A recognized key can appear in a schema, to require it. Its type is already fixed by the build, so declaring a different one (title "int") is a config error rather than a rule no page could satisfy.