HTML refactor

[david-christiansen]

The HTML templates for this site are extremely difficult for me to work on.

The CSS is the generated output of Tailwind, with the actual Tailwind config long-gone. Tailwind means copy-pasting a bajillion little formatting instructions all over the HTML, rather than using named classes - I think it makes sense as the output of something like JSX components or a richer templating language than Hakyll's, but here it's quite painful.

I'm going to use Hakyll's templates to refactor this to be as DRY as possible with partial, as a kind of holding pattern until I can get rid of Tailwind entirely and be able to actually maintain the site.

For now, this PR:

• Gets rid of the quirks mode warning in devtools by adding a DOCTYPE
• Factors out the "nested corners" blob that was copy-pasted everywhere and made it hard to read the content/template

[david-christiansen]

@jzwood, you've expressed an interest in helping out with the pages. Do you think that this is a reasonable approach? Can you see anything clearly inadvisable in my plan, or in what I've actually done?

[jzwood]

@david-christiansen Exactly the first steps I would have taken. Having the corners on every page was really painful. If I had the power to approve this PR I would. 😉

[jzwood]

Having the discipline to really standardize your website, decomposing it into a small cohesive set of primitives and building custom css for these components, is quite hard in practice.

You can pull a comprehensive UI framework off the shelf, such as bootstrap, but that can be its own painful source of complexity. You can pull something more minimal off the shelf, like Tailwind, with the idea that you now have the tools to build out your components with smaller UI components that work together. With bootstrap you have the least control and the most complexity, with Tailwind you have lots of control and medium amount of complexity, and writing all the CSS from scratch you have the most control and the complexity varies by the project.

[jzwood]

For this site it is not crazy to remove Tailwind. Having done a lot of UI work my words of caution are this: it is tempting to use css for all styling but that ends up being really hard to manage in practice. Ironically, I think it's the best idea to keep the most general styles in CSS (e.g. what do buttons, input fields, headers, checkoxes etc look like by default) and have all custom css as localized to where the styles show up as humanly possible.

Naively that means using the style attribute (and that can be okay sometimes) but smart money says that using some minimal CSS library such as Tailwind to handle custom structural stylings (e.g. spacing etc) will save you a lot of headache.

[david-christiansen]

Thanks for the feedback!

A big concern I have about Tailwind in particular is that it really seems to be designed to have a code generation step that slurps a config and outputs a minimal-ish CSS file for the site in question. Dealing with site build configurations and CI and such is already way to much of a timesink for me, and adding a rapidly-changing dependency in another programming language seems likely to lead to headaches. I'd very much like to avoid having the static site generator require something like Nix or Docker or more generally tools that aren't on most Haskell developers' machines or on Hackage. Do you know a good workaround for this problem?

My plan here is not so much to perfectly decompose everything, but rather get it into a state where specialized knowledge isn't needed, and something like occasional MDN lookups are enough. Perhaps factoring the box corners out will be enough to make my stomach not feel like I've swallowed a brick whenever I open the templates, and radical changes won't be necessary :)

[jzwood]

That is a fair concern. I'm a big fan of picking the simplest solution that works and I suspect that you are too.

In truth, this website is not that big nor that complex, so foregoing a css framework entirely and writing all of the css by hand is certainly a viable option. If considered deeply and executed with discipline, the end result is going to be the cleanest, smallest, simplest, and most maintainable product. Unfortunately, this path is essentially equivalent to creating a custom mini-css framework just for this site. This option requires many technical and design decisions. Overall, it's not terribly hard to put together something that technically works and is okay, but its very hard to make it excellent, in my opinion.

If I were a consultant tasked with replacing Tailwind with a simple/maintainable alternative, I would probably treat layout and palette as 2 separate tasks.

For layout, I would probably reach for a minimal css framework such as tachyons. Tachyons doesn't have a build step – it's just a css file you include directly once and never think about again. There are other minimal css frameworks with a similar philosophy and good documentation so onboarding people to adjusting layout shouldn't be too bad. In a world where more than one person updates the website, having a shared css library can be a helpful (but not infallible) mechanism for maintaining a consistent style.

For palette, I would probably make a custom theme where I canonized the current colors into css variables. When I was originally conceptualizing how to give this site a dark mode it made sense to me to decompose the website into 3 layers: background, middle ground, and foreground. Now all you need to do is tag middle and foreground elements and decide what the background color, text color, links, etc should be for these 3 layers and now you don't need to explicitly set colors anywhere like you see with Tailwind.

You don't have to do any of this, haha -- it's just my opinion, but it would be fun to help out with this effort. 😃

[david-christiansen]

I'll take a look at Tachyons - thanks. Even the version of it that uses CSS variables for customization seems to promote a build step in npm, but as far as I can see, that's just a minifier.

Are minifiers for CSS really important these days, if the server does gzip compression?

[david-christiansen]

You don't have to do any of this, haha -- it's just my opinion, but it would be fun to help out with this effort. smiley

Any assistance I can get with this would be lovely. Right now, updating the web site is a big time sink for me, and I'd really like to have that not be the case so we could use it more proactively to get value. Making it easier to maintain (by me and by random Haskell-minded volunteers) would be hugely valuable for the HF.

I can't guarantee that I'll merge any PR that shows up, but if you want to take on moving us this way, I'm very happy to work with you in whatever capacity I have the time for.

Thank you for all the advice and info so far!

[jzwood]

btw, I asked the Tailwind discord if it was a terrible idea to use the config-less Tailwind CDN in production and I was told to never ever do that which pretty much rules out that option.

[jzwood]

Just made this PR against this branch for some incremental improvement.

I also just noticed the nix configs 😬. I've never used nix before so I am not sure how those factor into building the site. I saw there was both a tailwind config and package.json in there -- do you you what the deal is with that?

[david-christiansen]

I actually hadn't noticed the Nix config before you pointed it out - I'd been under the impression that it had been deleted. It's certainly unused and bitrotted, and I know that the generated Tailwind has been edited in the meantime by hand. I suspect that they're a remnant of an earlier version of the site.

Thanks! And sorry for the slow turnaround on my side.