Switch from Jekyll to Zola

[alerque]

This is probably as much my personal taste as anything else, but I very strongly dislike Jekyll. And always have really. I don't like Ruby and I find the allowed repository layout and output very restrictive. The fact that GitHub heavily restricts which plugins can be used just adds frustration to my dislike.

These days publishing on GitHub pages can be done by almost any static site generator using Actions. At some point I'd like to covert the sources to a different SSG. My current favorite is Zola, but Hugo would also be in the running and there are half a dozen others that I consider good (and half a hundred I don't).

[rjmunro]

Can it be done in a way that the same source is both a static website and a Sile document - would make an interesting showcase of Sile.

[alerque]

I'm not exactly sure how you picture that. I think the answer is yes, but that's not the direction I am headed. I was just going to include the sources for example documents in the site repo and have the website builder display them in a gallery as source and render them as PDFs.

I think what you're asking about is whether the entire site could be a SILE document. While it could, that would also make it a PDF. SILE doesn't output HTML+CSS. I don't think a PDF only site is what we want. I contemplated converting the manual to Markdown and using something like mdBook (or CaSILE) to publish it to the web and make a PDF, but that would introduce several artificial limitations to the manual itself. Notably there are limitations of the web output that don't apply to SILE so the manual would not be able to showcase everything it did, nor would most of the output actually be actual output.

[simoncozens]

I think the suggestion is that we use some markup (say, Markdown) that the static web site templater ingests and also that SILE (with an appropriate preamble class) also ingests. It’s an interesting idea but our core Markdown support in SILE isn’t good enough (yes, yes, CaSILE etc) and I don’t think it’s worth writing a handler for a different markup format.

[jameschensmith]

I'd be interested in converting the source to a new SSG. I have similar feelings towards Jekyll. I could convert it to Hugo, but what are your feelings towards a JS SSG, like Astro or VuePress (or if there is any which you would suggest)? This would open up the ability to use formats like MDX.

Whatever you choose, if you would like me to work on this just let me know and I'll get started on it 😊 👍

[alerque]

Definitely interested in tag-teaming this!

Zola is still my favorite SSG, but I acknowledge it has some limitations too. My approach to it's lack of extensibility (e.g. only strict CommonMark input) by preprocessing anything that needs munging around before passing it to zola to assemble the whole site. Templating in Tera suits most of my needs and the ones I expect most of the ones we'll run into, but not being able to reach for tera.register_filter() does suck sometimes. Preprocessing & using Pandoc's Lua filtering is very powerful but takes a bite out of speed.

I don't have any Astro or VuePress experience positive or negative. The only JS based SSG I've used in production is Hexo and had mixed feelings. I've done virtually nothing in the entire JSX space. Frankly everything I've looked at to date has been a turn off, but I haven't looked much in a couple years and I'm willing to hear an argument for why MDX would bring something to the table over, for example, setting up shortcodes for creating any widgets we want to reuse. Given how fast those frameworks move I'm a little concerned about longevity/maintainability.

I've used Hugo some and don't hate it. Don't love it either, but if that's what you're willing to contribute I could be persuaded.

mdBook has a lot of interesting features and much more easily extensible than Zola, but also very strongly oriented towards book content and specific output layouts which probably don't serve most of the site. Finding a way to use the same source content for the SILE manual and an mdbook based docs site would be fascinating, but maybe not an alternative for the main site.

One thing I'd definitely like to see is a site that can be easily localized / partially localized in a way that's not a frightful hack.

[jameschensmith]

Regarding SSG choice, I personally tend to lean on the side of JS-based SSG's. There are many non-JS SSG's out there using many different templating engines while still requiring some JS anyways. A JS-based SSG would be flexible (code, style, and document linting/formatting; on-demand icons & CSS; scoped CSS). If you use an SSG like Astro, for example, you could take advantage of their partial hydration support for when dynamic content is needed.

If you aren't persuaded, though, I can do a conversion with Zola if that's what you'd like 😊

Finding a way to use the same source content for the SILE manual and an mdbook based docs site would be fascinating, but maybe not an alternative for the main site.

That would actually be a great idea. You could track that in a separate issue.

One thing I'd definitely like to see is a site that can be easily localized / partially localized in a way that's not a frightful hack.

You shouldn't have a problem with that with any of the mentioned SSG's 🙂

[jameschensmith]

@alerque, I have the day tomorrow to work on this. If you could respond to my previous message, that will give me direction on the work for tomorrow. Thanks! 😊

[alerque]

When I learned to program, wetness was a bad thing, the goal was DRY. All this talk of "hydration" has me confused. Jokes aside, while I can read and mostly understand the programming terminology I still don't see a use case for it in the context of this site.

That being said I don't feel a need to argue about it and I don't want to hold up progress on the site because it doesn't fit my ideal. The status quo is just-so-bad. If you do see an actual use case that will improve things for us then just go for it. There can't be much worse than Jekyll.

One extra thing to note when picking is that I do want whatever stack we use to be relatively easy to fire up via nix. I realize having packages available is more of a concern for Go/Rust/other based systems than JavaScript or Python ones which are quite likely to bootstrap themselves via npm / pip etc. I just want to be able to test build the site easily locally with access to all the other build tooling we'll need including the ability to run more than one version of SILE to generate examples (note we currently have access to run either/both of the last stable tagged version and the Git HEAD version when generating the site).

[jameschensmith]

😆 Say no more. Let's go with Zola 🙂 I'll get started migrating the site today. I'll probably need your help on the CI-side, so I'll set up a draft PR once I feel like I can't progress any further (like you said, tag-team 😊) 👍

[alerque]

Sure. Don't even wait until you get fully stuck, I'm not afraid of rebases and will keep an eye on stuff in a draft PR to see if there are bits I can help with along the way. Also usually on Gitter and IRC if more synchronous comms helps. No promises because of 2 small kids at my feet and lots other plates spinning...

[jameschensmith]

Quick update: There are two potential breaking changes that I'm running into when attempting to migrate SSG's. I'd like to not break URL paths, but the paginated path is probably less shared around than the post permalinks, and therefore probably less critical. Curious what your thoughts are on both.

1. Pagination will change from /blog/page:num to /page/:num (or /blog/page/:num if we want to be as close to the original as possible by overriding paginate_path).
2. Permalinks will change from /:categories/:year/:month/:slug to just /:slug. There's a potential to address this change if we override each post's slug or path. I also looked into doing transparent nested sections (organizing content by year & month), but transparent appears to only work one level. One final option would be to have redirect pages set up for all the current posts, and start new paths for future posts.

[alerque]

1. I don't care about the pagination links at all, the content on them changes with every new post anyway. I don't even thing there is a sane way to map them to a different scheme and they should probably be marked as not indexable anyway.

2. For posts we definitely don't want just top level /:slug, they need to be somewhere. If nothing else just so someday when we mix things up again we don't have a giant mess to unravel. I don't understand the limitation here since I've certainly done sites with multiple series of posts nested various ways, but.

   I do suggest picking some top level folder for our news feed posts. Mostly that has been release announcements, but it could be other things too. /blog/:slug or /news/:slug is probably okay, I don't know if we need the date nesting.

   Redirects from old URLs to new for the blog posts is fine. The current ones are pretty easy to derive from the post filenames and we could stuff the current slug into the posts meta data to make zola use the same slug in a different root path. That would make the redirect rule pretty easy to write.

[jameschensmith]

I don't care about the pagination links at all [...] they should probably be marked as not indexable anyway.

Got it. Makes sense! Thanks for addressing that point (and my other point as well 🙂).

I don't understand the limitation here since I've certainly done sites with multiple series of posts nested various ways, but.

Ahh, I can clarify 😅 Yes, sectioning through directories & subdirectories exist (also, I'm quite enjoying Zola during this migration 😊). What I was trying to describe was a situation where posts are located under ./content/blog/{year}/{month}/{slug}, I couldn't find a way to have a section at ./content/blog which lists all the posts under each of the grandchild directories ({month} in this example). Hope that makes sense.

Also, I 100% agree on not having posts at the top level. That was a mistake on my second point 🙈

[alerque]

Thanks for all the work on this @jameschensmith, at least as far as I'm concerned this is a great start and will make improving the site much more comfortable. There is a lot that can be done to improve it but the tooling was so awful it was hard to be motivated to touch it.