learnyouahaskell
Switch to Markdown
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:
-
[x] 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.
-
[x] merge CSS: #41 had some changes, and the upstream had some, especially in #64; this includes:
- [x] make sure Markdown-produced HTML fits with the CSS updates upstream
- [x] spot-check that the visual changes aren't too big; some examples here: https://github.com/learnyouahaskell/learnyouahaskell.github.io/pull/41#issuecomment-3573248287
- [x] 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.
- [x] 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 First thank a lot for adding the GitHub workflow, it helped a lot in this instance.
I brought all the textual change. There were few instance where the textual change was wrong so I took the liberty to update it. Feel free to adjust.
Let me know if you need more help!
@pierluc-codes terrific, thank you! (and sorry I wasn't around this week: stuff happens...).
I'll try to review the textual changes by the end of the week. I'm pretty sure, they should be fine!
In the meantime, we still should make sure styles are reasonable. In this comment you noticed several things, which aren't too bad, but the way the error message is formatted, probably needs some thought. Do you want to try to work on this front more? I see two options: (1) try to eyeball the text more and make a list of all noticeable styling changes; (2) try to fix some of these changes by updating CSS / MD / the way HTML is produced so that we have a better match with the original. THe second one is obviously more involved, so it's okay to take the first one or none at all. I hope to get to this by the end of week as well...
@ulysses4ever I eyeballed the doc and I think we are good. I did some correction here and there.
There is still a minor difference related to image size but to be honest I like the bigger images ;)
I would like to note that migration also fixed few mistake that were in the original HTML. Very cool.
Terrific! There are two big items on the list left (at least):
-
integrate CSS changes from https://github.com/learnyouahaskell/learnyouahaskell.github.io/pull/64 so that we have a decent mobile view
-
nuke old html and the generated files. This is not completely trivial because the generate.sh script starts failing if you simply remove that stuff. I need to understand better how the script works before I can act on this item.
@ulysses4ever I will be busy this week so I won't be able to push this forward for at least the next week. I can make time if you need a review on something.
Just an update: I managed to remove dependence on generated files and removed the files. I switched to responsive CSS but got stuck because there are two slightly different style.css in the repo, and they have existed from the very beginning. I want to kill one.
The responsive CSS patch from #64 is applied now. Next: merge upstream main to here so that we don't see all the conflicts.
I intended to do more spot-checking but this PR is ready for review now. @pierluc-codes
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
Hey all, it was a quiet week!.. @smith558 do you think you could conduct a formal review any time soon? It doesn't have to be in-depth, just the general approval for the direction of travel would be great (and we do require one approval at least...).
@pierluc-codes any plans to give it a final review? I hope we can merge it before New Year!
@ulysses4ever I did two minor correction. I think we are good. Feel free to merge when you are comfortable to.