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

Custom Data File Formats

Contents

Out of the box, Eleventy supports arbitrary JavaScript and JSON for both template and directory data files as well as global data.

Maybe you want to add support for TOML or YAML too! Any text format will do.

Note that you can also add Custom Front Matter Formats as well.

Usage Jump to heading

Filename .eleventy.js
// Receives file contents, return parsed data
eleventyConfig.addDataExtension("fileExtension", (contents, filePath) => {
  return {};
});
Filename .eleventy.js
eleventyConfig.addDataExtension("yml, yaml", (contents, filePath) => {
  // …
});

Usage with Options Jump to heading

Added in v2.0.0-beta.1

Filename .eleventy.js
// or with options (new in 2.0)
eleventyConfig.addDataExtension("fileExtension", {
  parser: (contents, filePath) => ({}),

  // defaults are shown:
  read: true,
  encoding: "utf8",
});

Examples Jump to heading

YAML Jump to heading

Here we’re using the js-yaml package. Don’t forget to npm install js-yaml.

Filename .eleventy.js
const yaml = require("js-yaml");

module.exports = eleventyConfig => {
  eleventyConfig.addDataExtension("yaml", contents => yaml.load(contents));
};

TOML Jump to heading

Here we’re using the toml package. Don’t forget to npm install toml.

Filename .eleventy.js
const toml = require("@iarna/toml");

module.exports = eleventyConfig => {
  eleventyConfig.addDataExtension("toml", contents => toml.parse(contents));
};

Adding a custom JSON file extension Jump to heading

Filename .eleventy.js
module.exports = eleventyConfig => {
  eleventyConfig.addDataExtension("geojson", contents => JSON.parse(contents));
};

Feed EXIF image data into the Data Cascade Jump to heading

Added in v2.0.0-beta.1 This uses the exifr package to read image EXIF data. Don’t forget to npm install exifr.

Note that the second argument is an object with a parser function.

Filename .eleventy.js
const exifr = require("exifr");

module.exports = function(eleventyConfig) {
  eleventyConfig.addDataExtension("png,jpeg", {
    parser: async file => {
      let exif = await exifr.parse(file);

      return {
        exif
      };
    },

    // Using `read: false` changes the parser argument to
    // a file path instead of file contents.
    read: false,
  });
};

Ordering in the Data Cascade Jump to heading

Note that in the data cascade there is a specific conflict resolution order when the same keys are used in data files. For example, JavaScript files take priority over JSON. These new custom data file formats are treated as lower priority than both JavaScript and JSON.

If you add multiple file extensions, the latter ones take priority over the earlier ones. In the following example, if there is ever conflicting data between *.toml and *.yaml files, the yaml file will take precedence.

Filename .eleventy.js
const toml = require("@iarna/toml");
const yaml = require("js-yaml");

module.exports = eleventyConfig => {
  // Lower priority
  eleventyConfig.addDataExtension("toml", contents => toml.parse(contents));

  // Higher priority
  eleventyConfig.addDataExtension("yaml", contents => yaml.load(contents));
};

Example Jump to heading

Consider the template data file search for a my-first-blog-post.md file. The order with custom toml and yaml formats (as seen above) will go as follows:

This same ordering would be used for template directory data files as well.

Other pages in Using Data:

Related Docs