Move from Bash/sed to Haskell/Hakyll for site generation

[ulysses4ever]

Hey all and happy holidays! I've spent my holidays (in part) porting the shell script (generate.sh) that converts Markdown to HTML to Haskell using the Hakyll library that assists in producing static websites.

I submit two commits: one just moves stuff from the markdown directory to the top level (makes sense after markdown became the only way to work with the website) and the other does the thing; this should ease reading the diff. In sections below, I discuss some high-level questions because I don't expect people to dive too deep in the Haskell implementation. Also, eyeballing the result is very welcome (see https://ulysses4ever.github.io/learnyouahaskell.github.io/).

Those who are interested in the implementation, though, can find it in the single Haskell file (sans templates), site.hs, which I tried to document with comments as much as possible. The resulting script has grown about 1.5x in size relative to generate.sh, but I think it's more readable, and you can follow it even if you're not familiar with Hakyll. The code is co-authored by GitHub Copilot.

Why move away from the shell script

1. Hard to maintain (subjectively). It uses pretty gnarly sed expressions to generate the table of contents (chapters.html), for instance.

2. It's not entirely portable (e.g. MacOS users reported some troubles, although they can be resolved).

Why use Haskell/Hakyll

1. First in class conversion tools: Pandoc, Hakyll's high-level DSL to describe routes and transformations, templating system

2. More portable.

3. It makes a point to use Haskell to produce a book about Haskell.

Downsides of using Haskell

1. Haskell is less known than Bash among the general population, so contributions and maintenance may be trickier. But there are challenges with bash/sed as well, as noted above. Overall, I think we are in profit. Also, casual contributors don't have to build the site: in most cases, editing markdown should be enough.

2. Bash/sed are omnipresent (the other side of the portability issue of course), whereas to build a Haskell application, you need special tools (I explain it in detail in the README). Again, just like with (1), I believe this downside is outweighed by the benefits.

Changes in HTML

We still use Pandoc, so the results are mostly intact. There are two simplifications I made to make the whole thing simpler.

1. Small margins for some H1 headers are gone. There were (seemingly) arbitrary margins for the chapter headings. They looked like artifacts from the past (e.g. WYSIWYG tools sometimes produce this sort of small random adjustments). So, I removed them.

2. Img-tags are left wrapped in p-tags. Generate.sh patched those with sed, and I could certainly re-implement it in Haskell but I see no point in this: visually, the result seems the same.

I believe these changes don't have any negative effect while simplifying the whole picture.

[ulysses4ever]

/cc @pierluc-codes @smith558

[pierluc-codes]

Impressive work @ulysses4ever! 👏

I don't think I will have time to review before new year, but I will make time before the 5th for sure.

Looking forward to approve this! :)

[ulysses4ever]

@pierluc-codes no rush! Thanks for replying and happy holidays!

[pierluc-codes]

@ulysses4ever My apologies. Coming back from the holiday was much more difficult than anticipated. I will do a first round of review this weekend.

[ulysses4ever]

@pierluc-codes no worries! Thanks for the update and looking forward to it!