A little website overhaul

Yes, yes, I know. I spend more time writing about the behind-the-scenes of this website than anything else. I did say this was a personal project but I’m also aware I’m far too invested in tweaking and redesigning things, thinking and rethinking them without moderation.

At the end of the day I’m having fun with this, so I don’t mind it too much. I guess it comes with being a beginner at something, all the excitement and wonder holds your time hostage until you either get tired enough or proficient enough and, well, I am neither.

So, onto the changes!

Semantic HTML

There are many advantages to using semantic HTML to structure a web page. It improves accessibility, making everything easier to parse and navigate. It makes the content of your website render well without CSS (e.g. inside an RSS reader, if the user has disabled custom styling on their browser etc). It keeps your code clean and organized. And those are just a few examples.

Using <div> and <span> is obviously not forbidden and they exist for a reason but they should by no means be used liberally, inappropriately or when there’s a semantic alternative available. That means using <aside> instead of <div class="sibebar">, <strong> instead of <span class="bold"> and so on.

When it came to the overarching structure of this website I always made sure everything was organized semantically, but while crafting more detailed layouts like the image grids I use in the media section, I was relying a lot on contextless elements and that needed to be rectified. It was pretty easy to do that, as I simply transferred the styling onto lists and figures. They look the same as they did before, but if you use a screen-reader or a text-based browser like w3m you’ll be met with a much nicer experience:

A screenshot my Media logs page rendered as text-only inside a terminal window

Sass

I migrated the stylesheet I made from CSS to SCSS. I realize it might be kind of overkill but I do like the file structure and organization that Sass provides¹. To be honest, it’s mostly an excuse for me to get acclimated with its inner workings.

What’s really nice is I don’t need any editor plugins or additional tools to compile the code, as Hugo already takes care of it for me with something called Hugo Pipes. It gives me quite a bit of control over the outputted CSS and it all happens by adding a few lines to the head of my HTML templates:

{{< /span>- $opts := dict "targetPath" "assets/css/main.css" "outputStyle" "compressed" "enableSourceMap" "true" "sourceMapIncludeSources" "true" "transpiler" "dartsass" }}
{{< /span>- $style := resources.Get "scss/main.scss" | resources.ToCSS $opts }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" />

Obviously I’m very much in my infancy when it comes to anything Sass-related but I’ve been really enjoying its nesting functionality (while not going too wild).

Content organization

If there’s something I’m really good at is overthinking. The content organization of this website has long bothered me and kept me from adding more pages because I simply didn’t like looking at a cluttered mess of files all sitting at the root of my content folder.

The solution was to move pages to their own sections: Resources and Media is where they live now and I feel much, much better.

Bookmarks page

I added a Bookmarks page where I link articles I come across, both for my own safekeeping and for those who may find them as interesting and/or useful as I have. I think it’s really cool to have pages like this on a personal site and I’m excited to keep adding to it over time.

Taxonomies

Posts now have their own special tags!

Not much to say about this since it speaks for itself and was extremely easy to implement. I’m kinda mad at myself for not having set this up from the get-go but better late than never!

Thoughts section

The Thoughts section has been changed so every entry will be listed out in full but also have its own dedicated page. Makes it easier to link them to other places and makes me feel validated in my microblogging ventures.

Achieving that wasn’t as easy as I imagined. Using Hugo to manage this website has been very fulfilling and allows me to do a lot of cool stuff effortlessly, but I ran into a really annoying issue with its Ugly URL system.

You see, every other section on this website uses Pretty URLs. Blog posts, for example, are set up so their path will be /blog/year/slug/. This very post works this way: /blog/2023/overhaul/. But I don’t really want the same for the Thoughts section, with the desired post path being /thoughts/post-title.html.

In theory, that should be a breeze. I’d just have go to Hugo’s config file and add these lines:

[permalinks]
  thoughts = '/thoughts/:title/'

[uglyURLs]
  thoughts = true

In practice, Hugo moves the index of the Thoughts section to the root of the website instead of simply leaving it inside its designated folder, making content organization problematic.

There’s an entire Github issue thread about this specific scenario that dates back to 2018 and still hasn’t been properly addressed. I had to use a workaround by a kind user who shared my woes. Thankfully it worked, but there’s always a chance a future update will break this configuration.

At least I’m not alone in thinking this sucks ass, I guess.

RSS

I’ve been neglecting this one for a bit, mostly because I knew that in order to fix it I’d have to think about how I organize and style my content. Now that I got those two things out of the way, I finally committed to improving my RSS feed.

It now includes the full text as opposed to a summary. Getting this done was so unbelievably annoying because relative URLs were breaking every link and image. This article on how to improve Hugo RSS feeds was a true life saver and solved this issue altogether but this whole saga shortened my lifespan by at least a decade.

I also added some styling to the feed itself that makes it human-readable:

A screenshot of my RSS feed that displays a nicely formatted list of recent blog posts

To do that, I added a stylesheet tag to my RSS file (similar to how you’d link a CSS stylesheet to HTML):

<?xml-stylesheet href="/assets/layout/style.xml" type="text/xsl"?>

My styling is based off of an About Feeds template that introduced me to the concept of styled feeds and provided instructions on how to get my own set up.

Check out my human-readable RSS feed.