5 things you need to know about Jekyll vs. 11ty Liquid includes
29 Jan 2021
Thinking about migrating from, say, GitHub Pages-flavored Jekyll to a newer SSG? Eleventy is probably your closest bet, because it allows you to stick to the Liquid templating language you know and love. But the heart of a well-componentized site generation model, includes, works a little differently between Jekyll and 11ty.
1: Naming the include
Jekyll
Name the file component.html
11ty
Name the file component.liquid
2: Referencing the include
Jekyll doesn’t quote the filename. 11ty does.
I think you can disable filename quoting if you don’t override .eleventy.js to allow parameterized includes, but you should allow parameterized includes.
Programmatically encapsulating the “variable scope” of things you’ve broken into separate pieces of business logic with parameters is good coding practice – even when you’re coding with web site templating languages.
Personally, I’m so sold on parameterized partials/includes, that it’s the reason I’m sticking with Liquid instead of switching to Nunjucks (1, 2), even though I’ve read Nunjucks can build faster on 11ty than Liquid.
Jekyll
{% include component.html %}
11ty
{% include "component.liquid" %}
Or, alternatively, 11ty lets you chop off the file extension:
{% include "component" %}
3: Passing parameters
Jekyll uses an equals sign. 11ty uses a colon.
Jekyll
{% include component.html someparam=somevariablename someotherparam="plain text here" %}
11ty
{% include "component" someparam:somevariablename someotherparam:"plain text here" %}
4: Receiving parameters
Within the codebase of the component you’re passing parameters to, Jekyll makes you refer to those parameters with the prefix include.. 11ty doesn’t.
Furthermore, I think Jekyll does this because such includes still have access to the variable scope of the context that called them, so it needs to distinguish scope (I was skimming, and the excellent article where this was covered in more depth than I discovered on my own is in my 2nd language, French). 11ty, on the other hand, restricts the codebase of components called via parameterized include to the variables passed as parameters.
(Edit: I almost certainly got this wrong. Ignore this section until this message disappears; see link in footnotes.)
Jekyll
<h2>{{ page.title }}</h2>
<p>{{ include.someparam }}</p>
11ty
<h2>{{ another_param_i_added_to_include_call_because_component_cannot_see_page_dot_url }}</h2>
<p>{{ someparam }}</p>
5: Enabling parameters
Jekyll
Jekyll comes with parameterized include calls built in. Nothing needed on your part.
11ty
You’ll need to put this inside the module.exports = (eleventyConfig) => {} curly braces of your .eleventy.js file, somewhere before the return statement:
// Make Liquid capable of rendering "partials"
eleventyConfig.setLiquidOptions({
dynamicPartials: true,
strict_filters: true,
});
Further reloading
Turns out the French article was a translation of one called Turn Jekyll up to Eleventy – lucky us! Also, I may have swapped which system has “leaky” scope – will inspect later & update the article.
