Chore: switch from Jekyll to Eleventy

[kaicataldo]

refs #536

This is a work in progress. I know we haven't officially decided to use Eleventy, but I wanted to give it a shot to see what cutting over would look like. It's not all working yet, but it's looking promising!

There might be a few small things I need to fix still, but this is looking good to me. Would love to see what others thinks.

Note:

Eleventy is pretty flexible and allows you to pick the templating engine you want to use. The default is liquid (which is what Jekyll uses), which made converting fairly straightforward. If we go this route, going forward we'll have more flexibility in terms of templating engines and overall project structure.

[ilyavolodin]

Just to make sure that I understand it correctly. The biggest advantage of switching to this is that we don't have go through the pain of installing Jekyll any longer, right? Cause otherwise, it looks pretty much the same.

[kaicataldo]

Yes, biggest benefit is that we'll be using a build tool that we can configure using JS. We'll consequently get rid of our dependency on Ruby. Build times also seem to be improved for me.

[kaicataldo]

I'll also add that this will give us a lot more flexibility in the future. It looks a lot like Jekyll right now for the sake of conversion.

[ilyavolodin]

I see. Well getting rid of Jekyll is a very powerful reason, I absolutely hate it:-)

[kaicataldo]

This is mostly working, if anyone else wants to play around with it! Known issues (feel free to edit):

• The fixable link at the top of every rule is broken. It's unfortunately generated in ESLint in the site generation script. I'll add a little hack on this end but we should change that if we decide to land this.
• The page title isn't being set correctly.
• RSS feed needs to be implemented.
• Syntax highlighting needs to be implemented.

[kaicataldo]

I'm not sure why Netlify isn't running...

[kaicataldo]

Ah, looks like it's running now 👍 Should be able to check the deploy preview to test it.

[mysticatea]

👍

[kaicataldo]

Some other notes:

1. Eleventy doesn’t allow YAML for data by default. There seem to be workarounds, but they involve monkeypatching and I’d like to avoid that.
2. It might be fixable with some more digging, but I had trouble rendering HTML in liquid loops in Markdown. It would output the correct markup, but it was encoded and so would render as a string. I ended up rewriting the problematic Markdown files as Liquid files, and I actually think it’s easier to read.

[kaicataldo]

Okay, I think I have everything working, down to syntax highlighting. 🎉

highlight.js's github theme is pretty much identical to the one we're currently using. I say almost because some characters aren't bolded, but otherwise it seems to be the same.

I converted some of the YAML data files into JSON because Eleventy doesn't support YAML for data out of the box. I would want to make sure I update the data generation script in eslint/eslint (at least until we try moving site generation into this repo).

The RSS feed doesn't load locally (probably some limitation with how browserSync is set up), but it does work in the deploy preview.

I believe this is ready for evaluation from the team! Please let me know if you see anything amiss.

[kaicataldo]

I believe this is ready to go! Will deploy sometime in the next few days.

[ilyavolodin]

@kaicataldo I pulled down this branch to try running it locally, but I can't seem to be able to either build or start anything. Here's the error below:

Converting YAML files found with glob "'_data/*.yml'" to JSON.
(node:20908) ExperimentalWarning: The fs.promises API is experimental
Trace: No files found for glob '_data/*.yml'.
    at c:\Users\Ilya\Documents\GitHub\eslint.github.io\_tools\yaml-to-json.js:37:17

I checked, _data directory does contain yml files, so I'm not sure why it's complaining.

When I run yaml-to-json command manually, everything seems to work fine.

[kaicataldo]

@ilyavolodin Thanks for checking this out! What Node version are you using?

[ilyavolodin]

I'm on 10.14.1 currently. I was able to manually compile everything and run it (bypassing npm scripts, which are still failing). Everything looks fine to me. But just to make sure, I'm currently running the site through crawler, to catch errors.

[kaicataldo]

Hmmm I'm unable to replicate locally on 10.17.0 on macOS. I wonder if it's a cross-compatibility issue in earlier versions of Node? I'll see if I can replicate on my Windows machine.

[kaicataldo]

Would be good to start running CI in a Windows env in this repo as well.

[kaicataldo]

I was able to replicate this in Windows 10 using Node 12.13.1. Probably some cross-compatibility issue.

[ilyavolodin]

Crawler finished testing local site. Everything looks pretty good. A few broken links, but I'm pretty sure those are broken in production as well. Here's the output:

http://localhost:8080/docs/maintainer-guide/governance links to missing page. List of links is ["http://localhost:8080/docs/maintainer-guide/contributing"]
Error 404 for http://localhost:8080/docs/maintainer-guide/contributing
http://localhost:8080/docs/6.0.0/user-guide/configuring links to missing page. List of links is ["http://localhost:8080/docs/6.0.0/rules/"]
Error 404 for http://localhost:8080/docs/6.0.0/rules/
http://localhost:8080/docs/5.0.0/developer-guide/working-with-rules links to missing page. List of links is ["http://localhost:8080/docs/5.0.0/rules/","http://localhost:8080/docs/5.0.0/rules/"]
Error 404 for http://localhost:8080/docs/5.0.0/rules/
http://localhost:8080/docs/5.0.0/user-guide/configuring links to missing page. List of links is ["http://localhost:8080/docs/5.0.0/rules/"]
http://localhost:8080/docs/4.0.0/user-guide/command-line-interface links to missing page. List of links is ["http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/","http://localhost:8080/docs/4.0.0/user-guide/formatters/"]
Error 404 for http://localhost:8080/docs/4.0.0/user-guide/formatters/
http://localhost:8080/blog/2016/02/eslint-v2.0.0-released links to missing page. List of links is ["http://localhost:8080/docs/developer-guide/code-path-analysis.html"]
Error 404 for http://localhost:8080/docs/developer-guide/code-path-analysis.html
http://localhost:8080/docs/2.0.0/developer-guide/working-with-rules links to missing page. List of links is ["http://localhost:8080/docs/2.0.0/developer-guide/code-path-analysis"]
http://localhost:8080/docs/2.0.0/developer-guide/code-path-analysis links to missing page. List of links is ["http://localhost:8080/docs/2.0.0/developer-guide/code-path-analysis/"]
Error 404 for http://localhost:8080/docs/2.0.0/developer-guide/code-path-analysis/
http://localhost:8080/blog/2015/06/eslint-0.24.0-released links to missing page. List of links is ["http://localhost:8080/blog/2015/preparing-for-1.0.0"]
Error 404 for http://localhost:8080/blog/2015/preparing-for-1.0.0
Total pages: 939. Errors found 7

[kaicataldo]

Okay, this is now working for me in Windows 10 on Node 12.13.1. @ilyavolodin Can you check if it all looks good on your end?

[kaicataldo]

Could this be an issue with Node 10? I actually set the engines as >=12.0.0, since that's latest LTS and I figured this is just for local dev. If that doesn't seem like a good idea, I can change engines to >=10.0.0 and see if I can debug this issue (might not be able to use fs.promises).

[ilyavolodin]

Everything is working fine for me now. Sorry about the noise, I forgot to run npm install after I pulled latest changes. npm run start now correctly starts local environment. It's still not blazingly fast, but it is much faster then Jekyll (not a huge achievement, turtles are faster then Jekyll:-)

[kaicataldo]

No problem! Appreciate the help :)

[kaicataldo]

Yes, I'd love to make it faster in the future. Note that in Jekyll we were excluding a bunch of files from the build to speed it up, which doesn't seem possible with Eleventy at the moment. Would love to figure that out going forward. I'm also hoping Eleventy will eventually get incremental build support - right now it rebuilds the whole world on every file change.