11ty

Eleventy Documentation

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:

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 

---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.8.4

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: using Front Matter Excerpts New in v0.8.4

Filename .eleventy.js
module.exports = function(eleventyConfig) {
  eleventyConfig.setFrontMatterParsingOptions({
    excerpt: true,
    excerpt_separator: '---' // Optional
  });
};

Now you can do things like this:

Filename sample.md
---
title: My page title
---
This is an excerpt.
---
<!doctype html>
<html>
…

This will not alter your template’s content in collections. Your excerpt will now be available in the template’s page.excerpt variable.

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.8.4

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.

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):

  1. Front Matter Data in a Template ⬅
  2. Front Matter Data in Layouts
  3. Template Data Files
  4. Directory Data Files (and ascending Parent Directories)
  5. Global Data Files