Front matter

745 words, 4-minute read

Content can define front matter name: value pairs between --- delimiters at the top of any file. These define meta data that can be used in in templates, the content, or even within other front matter fields.

Publican values #

All name: value pairs are defined on a single line. Values are optional, but Publican assigns special use to the following values.

title #

The page title, typically used in the HTML <title> and <h1> tags.

title: How to contact us

The page title used in menus. This is usually shorter than the title, for example:

menu: Contact

Set menu: false to remove the page from menus.

slug #

The page slug – the file location where the page will be built. The slug is usually set by the file’s name and directory but you can override it with a path relative to the build directory.

slug: custom/page/location/index.html

priority #

A page priority expressed as a real value from 0 (least important) to 1 (most important). The priority can be used to:

  1. Order pages in navigation. By default, Publican uses reverse priority order.

  2. Indicate the importance of pages in XML sitemaps.

priority: 0.7

date #

The post date in any JavaScript Date() format, e.g. 2025-12-25 or 2025-07-15T11:00:00.

date: 2025-01-23

Posts with future dates are rendered in development mode but do not appear on production sites.

publish #

The publication date. Set to:

publish: 2025-02-28

tags #

A comma-delimited list of tags relating to the page content, e.g.

tags: HTML, CSS, JavaScript

Publican can generate index pages based on these tags.

template #

When rendering HTML and markdown content, Publican uses default template named default.html located in the src/template/ directory. You can override this in any file.

template: post-template.html

index #

The search engine indexing frequency, as used in sitemaps and feeds. Typical values are daily, weekly, monthly, or yearly. Set it false if you want to omit a page from sitemaps.

index: weekly

debug #

Outputs the posts properties to the console when the file is loaded and parsed.

debug: true

Custom front matter #

You can add any front matter name: value pairs on a single line between the --- delimiters. For example, a description, author, and hero image information:

---
title: What are Static Site Generators (SSGs)
menu: false
description: An overview of what Static Site Generators.
author: Craig Buckler
tags: SSG, HTML, overview
priority: 1.0
date: 2025-01-23
hero: images/hero.jpg
---

The front matter name can be anything that’s a valid JavaScript variable name.

The front matter values can be used in content and templates with template literals, e.g.

<p>${ data.description || "Nothing to see here." }</p>

${ data?.author && `<p class="author">By ${ data.author }</p>` }

You can even use front matter values within other front matter values!

---
title: My title
menu: ${ data.title }
description: "${ data.title }" was written on ${ data.date } by ${ data.author }
date: 2025-01-23
author: Craig Buckler
---

Value types #

All custom front matter values are strings. Consider these values:

---
fmArray: [1,2,3]
fmObject: { a: 1, b: 2, c: 3 }
---

Template literals can cast strings to any type, e.g.

<p>array[0]: ${ JSON.parse( data.fmArray )[0] }</p>

<p>object.a: ${ JSON.parse( data.fmObject ).a }</p>

Alternatively, you could use a processContent function hook to parse the front matter when it’s loaded:

publican.config.js

publican.config.processContent.add(
  (filename, data) => {
    if (data.array) data.fmArray = JSON.parse(data.fmArray);
    if (data.fmObject) data.fmObject = JSON.parse(data.fmObject);
  }
);

Templates can then use the values directly:

<p>array[0]: ${ data.fmArray[0] }</p>

<p>object.a: ${ data.fmObject.a }</p>