Five Critical Things To Do Before Working With 11ty

I am a big fan of static site generators (SSGs), as many have noticed from reading this blog and following me on Twitter. I’ve recently been dabbling with 11ty (pronounced eleventy) and very impressed so far. While this SSG is generally excellent with low overhead, there are a few things developers may want to remember to do when starting their adventure with the static site generator.

Setup A .Eleventy.js File

Developers will want to set up a .eleventy.js file in the root of your 11ty project. This file will export our custom filters, methods, collections, and general configuration for our site. 11ty comes with an excellent out-of-the-box configuration, but most will be frustrated by a few of the default options.

Pick Your Template Engine

It feels like 11ty can handle any templating language we can throw at it. Supported file formats range from HTML, Markdown, Haml, and much more. Most starter projects start with Liquid, and to me is the most natural for folks coming from other SSG like Jekyll.

For folks choosing Liquid, remember to read the LiquidJS documentation to see what subset of Liquid syntax is supported.

Understand The Data Cascade

The data cascade is one of the most powerful features of 11ty and allows developers to access data naturally from any file or template. There are six levels:

Computed data
Front matter data in a template
Front matter data in layouts
Template data files
Directory data files
Global data files.

Understanding where our data is coming from helps us write and debug our site faster. Read more about the data cascade here.

Remember To Add Copy Passthrough

By default, 11ty will only process files that are part of its known file extensions. 11ty will not automatically copy static assets like images, css, and font files to our output directory. We’ll want to configure our passthrough copy folders and files in our.eleventy.js.

module.exports = function(eleventyConfig) {
  // Output directory: _site

  // Copy `img/` to `_site/img`
  eleventyConfig.addPassthroughCopy("img");
  
  // Copy `css/fonts/` to `_site/css/fonts`
  // If you use a subdirectory, it’ll copy using the same directory structure.
  eleventyConfig.addPassthroughCopy("css/fonts");
};

Add Custom Filters

Each project is unique, and developers can customize 11ty to solve a plethora of problems. As mentioned previously, LiquidJS only supports a subset of Liquid syntax. That’s ok since 11ty allows anyone to extend the processing engine with custom filters.

In the following example, we add an except filter and a filter that returns a category from a collection using a particular tag. We first register the global filters in our .eleventy.js file.

module.exports = function(eleventyConfig) {

    eleventyConfig.addFilter("exclude", function(values, ex) {         
        return values.filter(v => v !== ex);        
    });

    eleventyConfig.addFilter("withCategory", function(values, key) {                 
        return values.find(v => v.data.key === key);
    });

};

Then we can use them in our Liquid template.

<ul>
    {% assign taggers = tip.data.tags | exclude: "tips" %}          
    {%- for tag in taggers -%}
    {% assign category = collections.categories | withCategory: tag %}          
    <li>           
    <a href="{{ category.url }}" title="{{ category.title }}"> 
        {{ category.data.name }}
    </a> 
    </li>
    {%- endfor -%}
</ul>

Pretty awesome! Read more about custom filters here

Bonus: Read The Documentation

When in doubt, read the documentation. The 11ty team has done a great job writing the documentation and is an excellent resource for folks starting a new 11ty project.