Jekyll migration guide

[zachleat]

[DirtyF]

Happy to test and review it in you need an extra pair of 👀

[nhoizey]

Having @DirtyF review it would be awesome, as he manages documentation in Jekyll core team!

[paulrobertlloyd]

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).

[zachleat]

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]

Ah-ha, that seems like it makes sense. Will give it a go, thanks!

[zachleat]

@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.

[DirtyF]

@paulrobertlloyd were you able to complete your migration now that 11ty/eleventy#75 has shipped?

Anything worth mentioning in the migration guide?

[paulrobertlloyd]

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 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!

[zachleat]

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 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

[paulrobertlloyd]

In order of priority…

1. smartify
2. markdownify
3. jsonify
4. where/where_exp
5. 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?
6. 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.

[DirtyF]

Thanks @paulrobertlloyd for this tutorial:
https://24ways.org/2018/turn-jekyll-up-to-eleventy/

[zachleat]

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]

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]

@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.

[paulrobertlloyd]

@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]

@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]

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.