Move off Jekyll

[tannewt]

From discussion on #1200. It would be nice to support board renames well and we likely need to move off of Jekyll to do it. There is probably something simpler to use.

Jekyll used to be the only way to do the generation for GitHub Pages but it is now more generic with GitHub Actions.

[makermelissa]

Thanks for adding the issue. We would need to look into static website generators. Jekyll is the generator and uses Ruby as the language and Liquid as the template engine. We are probably not taking advantage of all of its features since I don't know Ruby and my only experience with Liquid is from working on this site and documentation for Jekyll/Liquid isn't the best.

It would be nice to use something most people who would contribute to the site know better like Python as the language. The Python Software Foundation has a list of them here: https://wiki.python.org/moin/StaticSiteGenerator

One of those that is coming up in searches is Pelican which makes use of Markdown and Jinja2 as the template engine, so transitioning would probably be easier.

Here is a great list of site generators with more detailed information https://jamstack.org/generators/. We may also want to look into something that uses JavaScript and React as the template engine (such as Docusaurus), but I think something that can read the existing markdown files should be a requirement. Also something that is easy to extend with features we need would be very useful.

[jwcooper]

It might be useful to find all of the limitations and hard edges we run up against to make sure most of the requirements are met on a new static generator. What are the limitations with the current site with jekyll?

It would be nice to continue without using react or any javascript frameworks. cp.org is very fast as a static site and is still fairly simple for most any user to contribute to. It should work with javascript disabled right now (missing a few features, of course) and doesn't use any javascript frameworks, complicated build pipelines or any special server infrastructure to host.

With board renames, couldn't we add a new redirect using a jekyll plugin? Something like this might work: https://github.com/jekyll/jekyll-redirect-from

[makermelissa]

It might be useful to find all of the limitations and hard edges we run up against to make sure most of the requirements are met on a new static generator.

Yep, definitely.

What are the limitations with the current site with jekyll?

With Liquid (Jekyll's template language), I'm having trouble when I try and do more complex things like display for instance, I was trying to modify the downloads page, which shows all the boards that are in the _data/files.json folder where the board_id matches currently, but also show them if the board_alias also matches. Then when it goes through the files, I didn't want it to show if the board name matched either the board_id or the board_alias in the json data. The filters for matching things are kind of limited, though I usually can figure out a workaround for things like this after playing around with it for a few hours, but as the workarounds pile up, the code gets harder and harder to modify without breaking something.

Originally, I had suggested kind of redoing the code to simplify it to get around that. As I mentioned above, we are probably not taking advantage of all of its features. For instance, it appears custom plugins could be written for liquid using Ruby Gems (see https://jekyllrb.com/docs/plugins/your-first-plugin/), which would probably solve some of the issues, but the learning curve is kind of high for people who haven't used ruby, such as myself, whereas with something that is Python-based, many of us are already familiar with Python or CircuitPython, so the learning curve is much lower.

Some other limitations I've run into are that without the incremental field, it takes around 1 minute to rebuild the site every time you make a little change and 2 minutes if more than 1 change was done. If incremental is on, it doesn't always rebuild properly. For instance I have it set up so if an image is missing for a board, it will display the unknown board image. If you add that image in, it's not smart enough to realize it should rebuild the html as well. Overall, I'd like something that was a bit faster.

It would be nice to continue without using react or any javascript frameworks. cp.org is very fast as a static site and is still fairly simple for most any user to contribute to.

Fair enough, I was merely suggesting using something like Docusaurus which would run when a PR is merged and create a static site just like it does now rather than a dynamic backend that requires special infrastructure. The main difference is it wouldn't feel so awkward to add features.

Anyway, my inclination is to lean towards something more Python-based anyways, but I didn't want to rule other good solutions out without doing more research.

[dhalbert]

I found Liquid to be a difficult template language to use. It was both awkward and weak. (I could use stronger words.) It's also hard to set up Ruby properly on Ubuntu now, for some reason.

[tkroo]

As an exploration, I implemented circuitpython.org using 11ty here: cp-org-11ty
This exploration is just for fun (and is unfinished) but might be helpful to this issue. Also it doesn't address the renaming/redirect issue.

11ty is nice because:

• You can create collections programatically. Which could make creating collections based on complex filtering criteria easier than doing it in liquid.
• You can use any of these templating languages: HTML, Markdown, WebC, JavaScript, Liquid, Nunjucks, Handlebars, Mustache, EJS, Haml, Pug (You can pick one or use them all together in a single project)
• And it is fast: On my machine initial site generation took 11ty 1.71 seconds vs Jekyll in 46.819 seconds.

However it is not written in and does not use python language.

11ty is also relatively similar to Jekyll:

• https://kittygiraudel.com/2020/11/30/from-jekyll-to-11ty/