The Equal Justice Initiative
Eleventy
The possum is Eleventy’s mascot
Eleventy Documentation
Menu
Compare npm install
Eleventy 5.81s
Remix 40.14s

Custom Front Matter Options

Contents

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: use JavaScript in your front matter Jump to heading

While the existing js front matter type uses an object literal, this example makes use of any arbitrary JavaScript and exports all of the top level variables and functions.

Here’s what this might look in a Nunjucks template:

Filename page.njk
---javascript
const myString = "Hi";

// export a function
function myFunction() {}
---
<!-- The template content goes here -->
<div>{{ myString }}</div>
<div>{{ myFunction() }}</div>
More advanced usage options 
---javascript
// async-friendly
const myAsyncString = await Promise.resolve("HELLO FROM THE OTHER SIDE");

// export via destructuring assignment
const { myKey } = { myKey: "myValue" };
const [ first, second ] = [ "first", "second" ];

// export via dynamic import
const { noop } = await import("@zachleat/noop");

// access Node.js globals like console.log
console.log({ noop });
---
<!-- The template content goes here -->

To enable this, use the following configuration:

Filename .eleventy.js
const { RetrieveGlobals } = require("node-retrieve-globals");

module.exports = function(eleventyConfig) {
  eleventyConfig.setFrontMatterParsingOptions({
    engines: {
      "javascript": function(frontMatterCode) {
        let vm = new RetrieveGlobals(frontMatterCode);

        // Do you want to pass in your own data here?
        let data = {};
        return vm.getGlobalContext(data, {
          reuseGlobal: true,
          dynamicImport: true,
        });
      }
    }
  });
};

Example: using TOML for front matter parsing Jump to heading

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
// Don’t forget to `npm install @iarna/toml`
const toml = require("@iarna/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>
…

Example: Parse excerpts from content Jump to heading

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.

INFO:
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 Jump to heading

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.

Related Docs