Introduction

Welcome to my new blog.

As I wrote in my previous entries, I was making changes to try to achieve an AAA WCAG accessibilty rating, but was severely limited by the awfulness of blogger.

My brother suggested looking into Static Site Generation, and so I settled upon Hugo, with the Stack theme in particular.

The transition itself hasn’t been completely smooth, but I’m managing to make it work.

First of all, installing Hugo itself was simple enough, as well as installing the Stack theme. Configuring the site to use the theme, on the other hand, was the first hurdle - the in the configuration, rather than setting the theme as “Stack”, it had to be set to “Theme-Stack-Hugo”. This was because the instructions for the theme said so, but really the theme could be given any alias (and I prefer “Stack”)

The next issue was with getting the posts to appear in the list - creating a new post in content/posts like the Hugo tutorial states didn’t work, even if the post wasn’t set to draft. Delving into the theme, I saw that the list would get everything that is implied by the mainSections part of the config (i.e. whatever is in content/whatever-is-stated-in-the-config). Thus, I added “posts” to the mainSections of the config. No dice. Turns out they need to be in content/post, which does make sense in a way - posts will be of type “post”, after all. This was also because such configurations need to be put somewhere other than the root - I don’t completely understand why things are split in this way, but it is what it is.

Migrating Posts

The next step was to migrate my blogger blog to here - looking at the different migration tools “blogger-to-hugo” seemed the best option, as it would also download the embedded images to include in the posts. This, too, proved a bit of a challenge. When migrating the posts, it had to be into a directory that didn’t exist yet - as if it would use mkdir but not handle an exception properly.

Fine, I can put them into a new directory then copy them all into the correct one.

The next problem was that it would fail if I had any empty, draft posts. Which I did.

Following that, it had inserted a lot of random crlf characters - pretty much after every 13th word. But it didn’t just insert one, it would insert 2. This completely broke the HTML in each post. All 115 of them.

I created an automated script to replace the crlf symbols, but there was some kind of encoding issue, which prevented any of the posts rendering, so I had to resort to doing it all manually. In a way, it’s a blessing - even if the script had worked, there would have been some manual work to be done, and there are some posts that I think should be purged. Still, wasted time is frustrating.

Markdown

Another issue is that the markdown it would generate for embedded images would also be broken. For example, in the Raziel Amigurumi post there were lots of images in tables, but there was one where it was by itself, and it generated the following markdown

[![](../images/thumbnails/2024-12-06-raziel-amigurumi-wings.webp)](../images/2024-12-06-raziel-amigurumi-wings.webp)

Whilst the link works perfectly fine, the thumbnail doesn’t, because the “..” in the path get stripped out when Hugo compiles. Trying to escape it resulted in “%56%56” in the path, which is also wrong. As such, I needed to replace all the image tags. Thankfully, I found the figure shortcode to be quite good for this.

Perhaps I could fork the repo for the migrator, to fix these issues, but that was problematic too, because:

1. It’s written in Python, and I have no experience in it. This can be overcome, but would take a while.
2. The page for the migrator points to a repo that no longer exists. So I can’t fork it. Maybe it exists elsewhere, but at this point it seems too much effort.

React

A big draw to my site, it’s current raison d’etre, is The Interactive Legacy of Kain Timeline

This currently uses React and MUI, but it has gone through a few interations. First it was Knockout and Bootstrap. Then I refactored it using Vue.js, and then I redid it again like it is now.

In doing those iterations, I gathered up a bit of debt (e.g. using Bootstrap definitions for the layout), so I had to use this opportunity to strip that out.

Using the MUI components, I found that the background colours were hard coded, and as such it looked weird in Dark Mode.

Thus I’ve had to spend a while refactoring the app so that it would instead use the CSS variables that the main site does. I hope this makes it visually pleasing in both modes.

There are still some irritations I want to resolve, but that will be for another day:

1. At the moment I have to program the app in a different repo, then copy the build files across
2. The Hugo page won’t allow me to use a shortcode to automatically detect the JavaScript and CSS files, so I have to manually change there injection declarations

Hopefully I can eventually integrate React into this workflow sucessfully, allowing for smoother development, and without forcing users to download files that won’t be used on their visits.

Altering the Theme

Though the theme allows for injecting custom CSS into it, I still thought it necessary to fork it to create my own repo

There were two main things I could achieve with this:

1. I could adjust the breakpoints - the default theme sets the max width of the page at various screen widths, but it only did this up to the third-largest breakpoints. This meant that when viewing the site on a wide screen, the page would take up very little actual space, which I did not like. Though this could be solved with custom CSS, I thought it better to itegrate it into the theme directly.
2. I’ve previously mentioned the Interactive Timeline, and there is a link to it in the sidebar. When I first created it, I also made a blog post with the same name. The sidebar code in the theme would set a link as active if the name of the page you are viewing matches the name of the page the link connects to. This meant that, when viewing that blog post, the link was set as active, even though it didn’t link to the post. This is, in my opinion, a pretty significant oversight, which I needed to correct. Thankfully, it turned out to be very easy to do so. I’ve even created a PR to try to fix it in the main branch.

Having the theme under my full control may also enable me to integrate React more easily, but I’m not sure at this moment in time.

PHP & Redirection

The old version of the site used PHP, not for anything spectacular, merely for the partial views. These are now handled by Hugo, making PHP redundant. However, these links have existed for years (in some cases decades), so in order to not break them I’ve had to create PHP pages that would be on the old paths, but that redirect to the new paths.

The main exception to this is the main index page, which linked to the blog. Now I have to effectively do the reverse - no longer redirect from here to the blog subdomain, but instead to have the blog subdomain redirect to the main index.

I think that should be easy to do with my domain name provider, but I will wait a few days afterwards, to ensure that the DNS tables have updated, before deleting the old blog.

Accessibility

As I’ve been banging on about for weeks if not months, part of my main motivation for this was to enhance the accessiblity of the site overall.

I think I’ve achieved that. I’ll keep scanning through pages to see what I can find, but at the time of writing, the only issues I can find relate to link sizes being too small to meet AAA standards (which is very difficult) and some best standards involving the “Related content” section at the bottom of the page.

To Do

Over all, though there is still work to do, I’m very pleased with the end result. Maybe now I can take a break and complete Y’s 7.

• Category colours - each category is assigned a colour, which is visible on the header for blog posts. On the sidebar, they are all uniform. I edited the theme to show the colours, but they looked gaudy. So not only do I want to enable the colours in the sidebar, but I want to pick better colours (and do so before I show them all together)
• Category images - Each category can have an image associated with it. I think that could make things look nicer.
• Blog Post Images - Each blog post can have an image associated with it. I tried this using the images contained within posts (where applicable) but it looked horrendous. I’d like to try again, but with different pictures.
• Related posts - A section at the bottom of the page that throws up a “Best Practice” warning, because it uses the same HTML as part of the blog post headers. I’d simply change this to a different partial to resolve the issue.
• Integrate React - see above. Plus, if I create any further apps (which I intend to do) then it would really steamline the workflow.
• GitHub actions - further streamlining would be to make it so that, when pushing to the GitHub repo for this website, that it would then update the files on the server. I don’t want to shift to GitHub pages for it (yet), so I’m setting a bit of a harder challenge for myself.
• Some kind of mobile app - Part of the reason updates are so rare, are because it’s a lot of effort to create a blog post. Though there is a Blogger app, it’s not nice to use IMHO. I would rather that I could do my own, that would commit to GitHub directly. Admittedly, Blogger did have functionality for updating via email, which I barely made use of, so maybe I’m making excuses.