ReferenceBuilt-in steps

frontmatter

Moves the YAML front matter of pages into their data and sets page.date.

The frontmatter step moves the YAML front matter of a page into its data and removes it from the content. It also sets page.date to the modification time of the source file, and can check that every page has some keys.

Shape map (no group-by)
Default match **/*.{md,html,liquid}
Default workflow yes, as pages

What it doesLink to this heading

The front matter is a YAML mapping between two --- lines at the start of the file:

---
title: Getting started
tags: [guide]
---
# Getting started

For each text file it consumes, the step:

  • sets page.date to the last write time of the source file (UTC), when the file has one. The value is read when a template or a step uses it: only what reads it runs again when the file's date changes and its content does not (see File dates);
  • merges the front matter values into the file's data: a nested object (page: { ... }) is merged into the existing one, lists and values replace the existing ones;
  • removes the front matter block from the content. A file without front matter keeps its content as it is.

Binary files, and the files that match does not select, pass through unchanged. Front matter that is not a mapping is an error (the front matter must be a mapping).

OptionsLink to this heading

Option Type Default Meaning
require string or list of strings none Keys every consumed file must have, in its front matter or in folder or site data. A key whose value is null counts as missing

ErrorsLink to this heading

A missing required key fails the file:

error: pages: /_content/nofm.md: required key 'description' is missing
error: pages: /_content/p.html: required keys 'title', 'description' are missing

ExampleLink to this heading

steps:
  pages:
    inputs: "**/*.md"
    uses: frontmatter
    with:
      require: [title, description]
  permalink:
    needs: pages
    uses: permalink
  render:
    needs: permalink
    uses: liquid
  markdown:
    needs: render
    uses: markdown
  write:
    needs: markdown
    uses: write
  • Pages
  • Template data: page.date and the name resolution order
  • data: folder data that require also checks
  • collect: sorts pages by date, else page.date

Esc to close