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.

Miscellaneous notes to self about Markdown migration

This isn't about includes, but some other issues I'm running into as I migrate legacy Markdown files are:

• I have to figure out how to get 11ty's Markdown parser to add id="some-slug" attributes to my header tags in the same spelling that Kramdown used so old links don't break, including the ones with forced slugs like this:

   ### `=` {#equals}

• I have to figure out what to do about my generous use of links inside italics, when markdown-it-attr can't handle them
  • Maybe this is a good opportunity to strip all {:target="_blank"} appearances from my legacy .md files and programmatically parse links into _blank as appropriate instead.
• I have to figure out a new syntax highlighter instead of rouge and make sure all legacy .md files work with it properly -- especially code blocks I've wrapped in raw Liquid tags. Or maybe I won't. Maybe I just need to make sure 11ty does <div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code>xy<span class="kd">zz</span>y</code></pre></div></div> instead of <pre class="language-javascript"><code>xyzzy</code></pre> like it wants to. Ah -- that span'll get me -- okay, I definitely need a preprocessor. And then I guess change my CSS just a bit.
  • I had to hand-edit the Prism theme I chose to also style Markdown fenced code blocks w/o a language
  • I had to tweak my HTML because I can't find a way to get Prism to wrap a <pre> in anything, like a Div, so I have nothing to style the "before" of for my language indicators, so I had to change the look & feel to make them fit inside the <pre> visually. Bummer.
• It seems that perhaps markdown-it doesn't understand, and therefore strip from HTML output, the markdown="block" attribute I've got in a lot of the HTML tags of my .md files, but it also seems to do the job that such an attribute forces Jekyll & Gatsby into, and who knows where I'll take these .md files next, so I guess I'll just leave it in, rather than Python it away.
• I had to regex-replace {:target="_blank"} to {target="_blank"} to go from Kramdown to markdown-it-attr. Wrote myself a little Python script & threw it into the 11ty repo's root folder.
• I had to regex-replace date: to publish_date: in the front matter of every post, since 11ty doesn't like Jekyll-formatted dates, and that seemed easier than restucturing the values of the dates while preserving comments and whatnot that might be in there. Wrote myself a little Python script & threw it into the 11ty repo's root folder.
  • Probably still need to give 11ty a sorting algorithm, now, based on publish_date. Haven't gotten around to things like post loops & such, though -- still just getting everything about <section id="main-content">...</section> of posts & pages to render correctly in 11ty.
• I had to install Bootstrap into my NPM environment and import it into my SASS, because it turns out I'd used some Bootstrap variables in my custom CSS when on Jekyll.