Front Matter Data #

Add data in your template front matter, like this:

---
title: My page title
---
<!doctype html>
<html>
…

The above is using YAML syntax.

Locally assigned front matter values override things further up the layout chain. Note also that layouts can contain front matter variables that you can use in your local template. Leaf template front matter takes precedence over layout front matter. Read more about Layouts.

User Defined Front Matter Customizations #

Here are a few special front matter keys you can assign:

permalink: Add in front matter to change the output target of the current template. Normally, you cannot use template syntax for variables in front matter, but permalink is an exception. Read more about Permalinks.
dynamicPermalink: Enable or disable template syntax for the permalink key. Read more.
layout: Wrap current template with a layout template found in the _includes folder. Read more about Layouts.
pagination: Enable to iterate over data. Output multiple HTML files from a single template. Read more about Pagination.
tags: A single string or array that identifies that a piece of content is part of a collection. Collections can be reused in any other template. Read more about Collections.
date: Override the default date (file creation) to customize how the file is sorted in a collection. Read more at Content Dates.
templateEngineOverride: Override the template engine on a per-file basis, usually configured with a file extension or globally using the markdownTemplateEngine and htmlTemplateEngine configuration options. Read more about Changing a Template’s Rendering Engine.
eleventyExcludeFromCollections: New in v0.8.0 Set to true to exclude this content from any and all Collections (those tagged in data or setup using the Configuration API).

Alternative Front Matter Formats #

Eleventy uses the gray-matter package for front matter processing. gray-matter includes support for YAML, JSON, and even arbitrary JavaScript front matter.

JSON Front Matter #

---json
{
  "title": "My page title"
}
---
<!doctype html>
<html>
…

JavaScript Front Matter #

Note that Liquid templates do not allow executing a function in output {{ currentDate() }}. However, the following example does work in Nunjucks:

Syntax Nunjucks

---js
{
  title: "My page title",
  currentDate: function() {
    // You can have a JavaScript function here!
    return (new Date()).toLocaleString();
  }
}
---
<!doctype html>
<html>
<!-- … -->
<body>
  <h1>{{ title }}</h1>
  <p>Published on {{ currentDate() }}</p>
  <!-- … -->

Add your own #

You can customize Front Matter Parsing in Eleventy to add your own custom format. We have an example to do this with support for TOML below.

Advanced: Customize Front Matter Parsing New in v0.9.0 #

Eleventy uses the gray-matter npm package for parsing front matter. gray-matter allows additional options that aren’t available by default in Eleventy.

Check out the full list of available gray-matter options. By default, Eleventy uses gray-matter’s default options.

Filename .eleventy.js

module.exports = function(eleventyConfig) {
  eleventyConfig.setFrontMatterParsingOptions({
    /* … */
  });
};

Example: Parse excerpts from content New in v0.9.0 #

Filename .eleventy.js

module.exports = function(eleventyConfig) {
  eleventyConfig.setFrontMatterParsingOptions({
    excerpt: true,
    // Optional, default is "---"
    excerpt_separator: "<!-- excerpt -->"
  });
};

Now you can do things like this:

Filename sample.md

---
title: My page title
---
This is the start of my content and this will be shown as the excerpt.
<!-- excerpt -->
This is a continuation of my content…

Your template’s content will include the excerpt but remove the separator:

This is the start of my content and this will be shown as the excerpt.
This is a continuation of my content…

page.excerpt now holds This is the start of my content and this will be shown as the excerpt.

Don’t want your excerpt included with your content? The unique feature of this configuration is that you can keep your excerpt right at the beginning of your content. You can add a delimiter where you want the excerpt to end and the rest of the content to begin. If you want the excerpt to be separate from the content, make a new key for this and store it separately in your front matter or a data file.

Changing where your excerpt is stored #

If you don’t want to use page.excerpt to store your excerpt value, then use your own excerpt_alias option (any valid path to Lodash Set will work) like so:

Filename .eleventy.js

module.exports = function(eleventyConfig) {
  eleventyConfig.setFrontMatterParsingOptions({
    excerpt: true,
    // Eleventy custom option
    // The variable where the excerpt will be stored.
    excerpt_alias: 'my_custom_excerpt'
  });
};

Using excerpt_alias: 'my_custom_excerpt' means that the excerpt will be available in your templates as the my_custom_excerpt variable instead of page.excerpt.

Example: using TOML for front matter parsing New in v0.9.0 #

While Eleventy does include support for JSON, YAML, and JS front matter out of the box, you may want to add additional formats too.

Filename .eleventy.js

const toml = require("toml");

module.exports = function(eleventyConfig) {
  eleventyConfig.setFrontMatterParsingOptions({
    engines: {
      toml: toml.parse.bind(toml)
    }
  });
};

For more information, read this example on the gray-matter documentation.

Windows users: There is an upstream issue with the TOML dependency used here: Expected "\n" but end of input found., logged at Eleventy #586.

Now you can use TOML in your front matter like this:

Filename sample.md

---toml
title = "My page title using TOML"
---
<!doctype html>
<html>
…

Sources of Data #

The order of priority for sources of data is (from highest priority to lowest):