Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jekyll migration guide #68

Closed
zachleat opened this issue Feb 21, 2018 · 16 comments

Comments

Projects
None yet
5 participants
@zachleat
Copy link
Member

commented Feb 21, 2018

No description provided.

@DirtyF

This comment has been minimized.

Copy link

commented Feb 21, 2018

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

@nhoizey

This comment has been minimized.

Copy link
Contributor

commented Feb 21, 2018

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

@paulrobertlloyd

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member Author

commented 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

This comment has been minimized.

Copy link
Contributor

commented Mar 5, 2018

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

@zachleat

This comment has been minimized.

Copy link
Member Author

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

zachleat added a commit that referenced this issue Mar 5, 2018

@DirtyF

This comment has been minimized.

Copy link

commented Apr 21, 2018

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

Anything worth mentioning in the migration guide?

@paulrobertlloyd

This comment has been minimized.

Copy link
Contributor

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

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

This comment has been minimized.

Copy link
Member Author

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

This comment has been minimized.

Copy link
Contributor

commented Apr 22, 2018

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

This comment has been minimized.

Copy link

commented Dec 11, 2018

@zachleat

This comment has been minimized.

Copy link
Member Author

commented 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 zachleat added the needs-votes label Jan 8, 2019

@zachleat

This comment has been minimized.

Copy link
Member Author

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

@zachleat zachleat closed this Jan 8, 2019

@jeremenichelli

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link
Contributor

commented 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

This comment has been minimized.

Copy link

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.