5 things you need to know about Jekyll vs. 11ty Liquid includes
Tags: jamstack, webdev, eleventy, jekyll
Published: 2021-09-08 21:26:30

---
title: 5 things you need to know about Jekyll vs. 11ty Liquid includes
published: true
date: 2021-01-29 15:00:00 UTC
tags: jamstack,webdev,eleventy,jekyll
canonical_url: https://katiekodes.com/liquid-includes-jekyll-vs-11ty/
---

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](https://iainbean.com/posts/2020/flexible-components-in-eleventy-with-nunjucks-macros/), [2](https://stackoverflow.com/questions/56150714/how-do-i-include-the-same-partial-multiple-times-with-different-content-using-nu))_, even though I've read Nunjucks can build faster on 11ty than Liquid.

### Jekyll

```liquid
{% include component.html %}
```

### 11ty

```liquid
{% include "component.liquid" %}
```

Or, alternatively, 11ty lets you chop off the file extension:

```liquid
{% include "component" %}
```

## 3:  Passing parameters

Jekyll uses an equals sign.  11ty uses a colon.

### Jekyll

```liquid
{% include component.html someparam=somevariablename someotherparam="plain text here" %}
```

### 11ty

```liquid
{% 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](https://jamstatic.fr/2018/12/12/passer-de-jekyll-a-eleventy/) 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

```liquid
<h2>{{ page.title }}</h2>
<p>{{ include.someparam }}</p>
```

### 11ty

```liquid
<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:

```javascript
// 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](https://24ways.org/2018/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](https://github.com/arve0/markdown-it-attrs/issues/124)
  * 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.