You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
May 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.md and it’s not clear to me (beyond adding a permalink value 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).
@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.
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 -->
{{ 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:
Only by writing this comment and testing the above have I realised what values get prefixed with data and 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.yml to a file called site.json in the _data directory, 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 Santos
Reacted by Frank Taillandier, Zach Leatherman, Juan Caicedo, Alan, Robin Rendle and Adilson Santos
Just a quick reply here before I respond more in-depth.
I believe that it was all templateContent originally and that content is just an alias? Not 100% sure. But, for the record, a template can’t access its own templateContent, 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
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 smartify would be right up there; it was one of the first filters I implemented.
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.
@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.yml to .eleventy.js, the need of a _data.site.json if 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!
Activity
DirtyF commentedon Feb 21, 2018
Happy to test and review it in you need an extra pair of 👀
nhoizey commentedon Feb 21, 2018
Having @DirtyF review it would be awesome, as he manages documentation in Jekyll core team!
paulrobertlloyd commentedon Mar 3, 2018
May 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).Use `page.date` to set permalink with date variables. Related to #68 h…
zachleat commentedon 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
paulrobertlloyd commentedon Mar 5, 2018
Ah-ha, that seems like it makes sense. Will give it a go, thanks!
zachleat commentedon Mar 5, 2018
@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.
Fixes #74, related to #68
DirtyF commentedon Apr 21, 2018
@paulrobertlloyd were you able to complete your migration now that 11ty/buildawesome#75 has shipped?
Anything worth mentioning in the migration guide?
paulrobertlloyd commentedon Apr 22, 2018
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:
Whereas Liquid JS uses Shopify’s syntax:
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:
but when looping through items you need to use the following:
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!
zachleat commentedon Apr 22, 2018
Wow @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.Any in particular a priority? That’s quite a list there
paulrobertlloyd commentedon Apr 22, 2018
In order of priority…
smartifymarkdownifyjsonifywhere/where_expxml_escape,cgi_escape,uri_escapeOf course, this is just my 2¢. But
smartifywould be right up there; it was one of the first filters I implemented.DirtyF commentedon Dec 11, 2018
Thanks @paulrobertlloyd for this tutorial:
https://24ways.org/2018/turn-jekyll-up-to-eleventy/
zachleat commentedon Jan 8, 2019
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
zachleat commentedon Jan 8, 2019
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 👍!
jeremenichelli commentedon May 16, 2019
@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.paulrobertlloyd commentedon May 17, 2019
@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.
jeremenichelli commentedon May 19, 2019
@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!
alexpearce commentedon Jun 22, 2020
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.