Creating This Site

Currently, this site is hosted on Linode as I prefer to keep out of the AWS ecosystem when I can. I originally attempted to build this site using Hugo along with the alageek theme. But I ran into so many issues and small annoyances with how Hugo (and my desired theme) worked that I decided to rewrite the same general site and theme using Nuxt and TailwindCSS. You can see the result of this rewrite at https://git.st37.dev/st37/st37.dev

In this post I'm going to write down the issues and annoyances that I encountered when building this site to hopefully prevent myself from getting stuck again in the future.

Hosting

I decided on hosting on Linode since I wanted something cheap and simple. However, there were a few limitations with what Linode can do that made working with it just a bit annoying compared to something more bloated like AWS.

This site's content is statically generated content through Nuxt. I wanted to just publish these generated artifacts up to Linode's object storage, however I ran into the issue that Linode doesn't support ALIAS records (or any alternative) in their DNS platform. So, when using their object storage and bundled static website hosting (from the bucket), you cannot map the bucket's hostname to the apex (root) of the domain. So I would be stuck with a legacy address using the www subdomain which I prefer to not use.

So after hours of attempting to search around for a method of setting up a CDN layer to handle the proxying of connections through to the bucket under an elastic IP, I couldn't find any single way of doing it entirely with Linode's tools. I gave up and just decided on using a "Nanode"-sized machine to host the site using NGINX. This is still barebones enough for me not to be super annoyed, but I hate that their object storage website hosting doesn't have decent support for hosting through apex domains yet. Something to improve.

Static Site Generation

Even though I am hosting this site through a machine using NGINX (without a proper CDN), I still wasn't going to host non-static content. I figured using something like Hugo would be a good first step. I also decided on a simple monospace-only theme alageek which makes the post content simple and straightforward to read without looking empty but noisy (like most blogs nowadays).

Hugo

On its own, Hugo isn't a bad product, but IMO it is annoying to work with compared to JS-based alternatives. IMO, since you are developing for the web, it makes more sense use web-based (JS-based) technologies. Regardless, my first attempt to use Hugo was fine, but not optimal.

One BIG issue I wanted to resolve is the alageek theme not bundling its JS dependencies. It makes use of highlightjs, progressively, and bootstrap but only fetches them from a CDN (jsdelivr). This means that if I disallow additional scripts to run on a page (shoutout NoScript) or I want to do local development without an internet connection, I can't do much since I can't fetch the assets from jsdelivr. This is a really annoying practice and I would recommend that anyone not bundling assets into their site to look into actually distributing the content and logic they depend on.

I took a stab at attempting to swap out the script and style partials declared by the theme to bundle assets using Hugo's pipes for JS bundling. But that did not work as expected; the available tree-shaking kinda sucks and asset bundles become bloated and slow down the initial load of the site when bundling something as huge as boostrap and highlightjs.

Fonts were also fetched from Google which I don't really like. Just download the variable .ttf and serve it as part of your own CSS. This wasn't super straightforward within Hugo either.

Nuxt

So instead of trying to fix every issue I ran into with Hugo and a prebuilt theme, I just gave up. Instead I rebuilt the site using a tool I am already somewhat familiar with (Nuxt) and I know can handle all the use cases I will need. Ultimately it only took maybe a day of my free time to get a full site generated that visually mimicked the theme I wanted to use. And, honestly, I think it works cleaner and better than any of my attempts with Hugo.

Nuxt Content

To handle Markdown document rendering, you obviously should be using Nuxt Content if you are using Nuxt at all. This plugin supports so many different use cases of using Markdown as a CMS, that it is much more powerful out of the box than Hugo IMO.

The article content of this site is all written in Markdown and supports all the little features you might expect. Additional features such as read time estimation had to be done with a custom Nuxt server plugin that adds in additional details to the posts after parsing the files. Generation of the sitemap and the RSS feed formats was done through several Nuxt server routes that are marked for pre-rendering in Nuxt's configuration.

Tailwind CSS

Tailwind supports JIT compilation (in preview) which can significantly cuts down the size of the required CSS as compared to what the Hugo alageek theme is doing. The syntax of using Tailwind compared to Bootstrap is pretty similar, we just have the benefit of being able to tree-shake it and minify it down further when we build and deploy the asset ourselves.

Ultimately, the creation of this site wasn't too burdensome, but I spent too much time trying to get Linode and Hugo to do things they are not built to handle. I could acheive the same end result making use of free site hosting through Github, but then I wouldn't own the hosting of the content I publish (which I want).