Repository navigation
Jekyll migration guide #1851
Description
Activity
Happy to test and review it in you need an extra pair of 👀
Reacted by Nicolas HoizeyMay I add a request that this migration guide covers how to simulate permalink rewriting on a collection basis? Currently I have files saved in a locations such as
src/collections/_posts/YYYY-MM-DD-slug.mdand it’s not clear to me (beyond adding apermalinkvalue to each post) how I would manipulate the output path (in the case cited above, I would like the resulting file to be available at/YYYY/MM/slug.html).Reacted by Jim Fisher and Heather Booker- added a commit that references this issue
on Mar 5, 2018 Good call @paulrobertlloyd. Just as a stopgap measure to point you in the right direction, I’ve added an additional example to https://github.com/11ty/eleventy/blob/master/docs/permalinks.md#use-filters which you can add to a Directory Specific Data File: https://github.com/11ty/eleventy/blob/master/docs/data.md#template-and-directory-specific-data-files
Ah-ha, that seems like it makes sense. Will give it a go, thanks!
@paulrobertlloyd You may want to wait for 0.2.15 to try this. I’m adding a few more test cases around this behavior and found some failures that you might run into! It’ll be coming in the next day or so.
@paulrobertlloyd were you able to complete your migration now that 11ty/buildawesome#75 has shipped?
Anything worth mentioning in the migration guide?
Still working on it! With roughly the same number of pages, build time for ~620 pages is around 12 seconds with 11ty, whereas with Jekyll (that also involves some asset pipelining) I’m hovering around the 40 second mark. So a marked improvement, but pretty sure compilation could be even faster with caching, incremental updates and other such optimisations.
Anyhow, in answer to your actual question (!) @DirtyF, here are my learnings so far…
Liquid templating
One of the main things that would need covering is the differences between Jekyll’s Liquid implementation, and that of Liquid JS. For example, Jekyll’s include syntax follows this pattern:
<!-- page.html --> {% include include.html value="key" %} <!-- include.html --> {{ include.value }}
Whereas Liquid JS uses Shopify’s syntax:
<!-- page.html --> {% include "include.html", value: "key" %} <!-- include.html --> {{ value }}
There are also a number of useful filters available in Jekyll that are not available out of the box with 11ty. Perhaps some of these should be included as universal filters @zachleat?
Querying Data
It would also be really helpful if there was some documentation that explained how to query page data, as it’s not immediately clear right now. As far as I can tell, you can use the following variables when writing a page template:
{{ page.url }} {{ page.date }} {{ page.fileSlug }} {{ page.inputPath }} {{ page.outputPath }} {{ content }} {{ title }} {{ myFrontmatterKey }}but when looping through items you need to use the following:
{{ item.url }} {{ item.date }} {{ item.fileSlug }} {{ item.inputPath }} {{ item.outputPath }} {{ item.templateContent }} {{ item.data.title }} {{ item.data.myFrontmatterKey }}Only by writing this comment and testing the above have I realised what values get prefixed with
dataand when! It makes sense, but it wasn’t immediately obvious. That said, I’m still confused by the difference between{{ content }}and{{ templateContent }}, and when to use which! Is the above correct? It feels a bit inconsistent, as of now.Configuration
Finally, I think there would need to be a description of where Jekyll’s configuration values should exist in the world of 11ty. For example, I moved many of the values stored in my
_config.ymlto a file calledsite.jsonin the_datadirectory, which allowed me to continue using variables such as{{ site.name }}and{{ site.author.url }}. Also, whereas Jekyll’s collection configuration sits in the one file, in 11ty you need to create collection queries in.eleventy.js, but define any defaults (permalinks, layouts, default meta values, etc.`) inside a separate JSON file within each collection folder.
To be clear, I have no problem with the above changes, but should you have a Jekyll site that is particular customised, or makes use of many of Jekyll’s features, a bit of work is needed to achieve the same result using 11ty’s equivalent features. Therefore, this document would almost need to take each feature of Jekyll in turn, and explain how your existing configuration should be adapted. Of course, I’d be more than happy to help with this effort!
Reacted by Philipp Rudloff, Frank Taillandier, Zach Leatherman, Ege Esin, Donovan Glover and Adilson SantosReacted by Frank Taillandier, Zach Leatherman, Juan Caicedo, Alan, Robin Rendle and Adilson SantosWow @paulrobertlloyd, thank you for this! Super helpful!
Just a quick reply here before I respond more in-depth.
I believe that it was all
templateContentoriginally and thatcontentis just an alias? Not 100% sure. But, for the record, a template can’t access its owntemplateContent, this key is used in layout templates for the child content insertion point.There are also a number of useful filters available in Jekyll that are not available out of the box with 11ty.
Any in particular a priority? That’s quite a list there
Reacted by Paul Robert LloydIn order of priority…
smartifymarkdownifyjsonifywhere/where_exp- Perhaps a selection of data formatting shortcuts? Jekyll has a few, but not sure if you’d want to implement all of them to enable better compatibility?
- Escapes:
xml_escape,cgi_escape,uri_escape
Of course, this is just my 2¢. But
smartifywould be right up there; it was one of the first filters I implemented.Reacted by Roberto C Navarro and ⁂ TommiReacted by ⁂ TommiReacted by ⁂ TommiThanks @paulrobertlloyd for this tutorial:
https://24ways.org/2018/turn-jekyll-up-to-eleventy/While Paul did write the guide up (thank you Paul!) there is still some gold in here that needs to be mined so I’m putting this into the documentation queue
This repository is now using lodash style issue management for documentation requests. This means documentation issues will now be closed instead of leaving them open.
View the documentation queue backlog here. Don’t forget to upvote the top comment with 👍!
@paulrobertlloyd I'm currently migrating from Jekyll to Eleventy so I can help out if you want with this migration guide and content. I think it would be a great addition and real need for the official documentation.
I think the pitfalls people is gonna fall more is in the switcheroo between
_config.ymlto.eleventy.js, the need of a_data.site.jsonif they are consuming global data from Jekyll config, collection config and permalinks, and frontmatter passed directly from pages to templates/layouts as you mentioned.Reacted by Frank Taillandier, André Jaenisch, Daniel Schildt and ⁂ Tommi@jeremenichelli If people are interested in updating, improving and extending the article I wrote for 24ways and adding it to the official docs, I’d be open to helping and guiding that effort.
@paulrobertlloyd it would be great to jin forces and come up with some piece that can live in the official docs to avoid people openning duplicated issues or roaming around the repo when the face some of these things. I'll read your article and join my findings and if I see something good comes from it I'll let you folks know. Thanks!
Sorry for bumping an old thread, but I wasn't aware of an official guide and wanted to throw my blog post in to the mix, in case it's of any help.
Reacted by Matthew Blott- locked and limited conversation to collaborators
on Nov 3, 2025
