Switch to Markdown

[ulysses4ever]

This is a new life for #41 (opened in Nov 2022 and abandoned since) and the project!
The PR's version of the site is currently deployed at https://ulysses4ever.github.io/learnyouahaskell.github.io/.
Sadly, because of the many changes, both structural and little but pervasive, the HTML diff isn't very useful. (The Markdown diff is useful.) Hence, the reviewers are advised to open and eyeball the deployed version.

Below I detail main changes that this PR brings.

Main Changes

[1] Makes HTML generated from /markdown/source_md straight to /docs with Pandoc (which becomes a dependency of the project).

• use the new Makefile to generate the HTML (make) and to clean it up (make clean).

[2] Removes all HTML files that can be generated: docs/*.html and markdown/generated_html, except docs/index.html. Also removes markdown/generated_md (only used as a temporary directory really). This was a HUGE point of confusion for external contributors --- having several versions of the same thing.

How's HTML

[3] There are many small changes to the generated HTML vs the current one mostly because the current one is pretty irregular (no closing </p> tags, some weird combination of p and img tags, etc.). The many changes are meticulously recorded in the commit history inherited from #41.

Visually the result looks almost the same (please, double-check!), modulo slight changes in how text flows around images, but that doesn't seem consequential in any way.

How's CSS

[4] There doesn't seem be any changes on main since #41 was forked except for the responsiveness PR #64, which I manually applied.

How's textual content

[5] There has been many little text changes since #41 was forked. @pierluc-codes carefully re-implemented them here and I cross-chcecked it.

Minor cleanups and updates

[6] GitHub Workflow will now deploy the website by generating HTML from MD (obviously).

[7] generate.sh was cleaned up a bit, including with shellcheck.

• future TODO: create a CI workflow to check that shellcheck is clean.

[8] there was duplication of style.css/reset.css (they lived both under /docs and under /docs/assets/css). There's now only one version (/docs/assets/css).

[9] Similar to [8], JS files for the syntax highlighter that lived under /docs were moved to a more appropriate place under /docs/sh (the directory was there before and held one file already).

[10] The new .gitignore excludes the generated files under /docs.

---

old description

TODO:

• add textual changes since 2022; they have been collected by @pierluc-codes here: https://gist.github.com/pierluc-codes/9c07c421c087ab114c4456f6eb4f44ae

  • the current idea: @ulysses4ever goes from the top of the list in the Gist, and @pierluc-codes goes from the bottom. But we are both busy, so any help is welcome.

• merge CSS: Make preparations for switching to markdown-generated HTML #41 had some changes, and the upstream had some, especially in Make CSS responsive to improve mobile layout #64; this includes:

  • make sure Markdown-produced HTML fits with the CSS updates upstream
  • spot-check that the visual changes aren't too big; some examples here: Make preparations for switching to markdown-generated HTML #41 (comment)
  • nuke old html and possibly other generated files. This is not completely trivial because the generate.sh script starts failing of you simple remove that stuff. I need to understand better how the script works before I can act on this item.
  • de-dup CSS files (eg style.css)

---

The current version is rendered here: https://ulysses4ever.github.io/learnyouahaskell.github.io/chapters.html Note for @pierluc-codes : I had to change the repository I worked from (it used to be ulysses4ever/learnyouahaskell-md) because I cant open pull requests from non-forks.

[ulysses4ever]

I intended to do more spot-checking but this PR is ready for review now. @pierluc-codes

[ulysses4ever]

@pierluc-codes this was in the original PR and you removed it recently. I'm not sure what's going on here: I haven't studied this Pasndoc option. My guess would be that we make sure Pandoc doesn't try to highlight anything because we supply our own JS highlighter. The result seem fine with this option at least?

[ulysses4ever]

I made a big final sweep and this is ready for review now. This is a big change, so I'll ping all codeowners hoping to get more eyes on it. The result would benefit from eyeballing more. I also update this PR's description (see at the top) with a list of notable changes. Please, check it out...

It'd be good to merge it this week because there are many PR's on the repo that will benefit from rebasing on this.

@smith558
@konsumlamm
@xogcox
@memowe
@pierluc-codes