I finally migrated everything over to a static site generator (SSG). It took several rough days of repetitive HTML to Markdown conversion, but it’s all done now. This is the best and biggest change I’ve made to this website so far, no handcrafted HTML files to give me headaches anymore. I should have migrated much earlier or used an SSG from the beginning, either would have significantly reduced the amount of problems I had.
Up to now, all the HTML on this website was handcrafted. This means that every post, including very long ones such as this, was written from scratch using a boilerplate file. For example, here’s a snippet from above:
<h2>You don't need to play Sophie 1</h2>
<p>Sophie 2 is a direct sequel to Sophie 1. Before Sophie 2 came out, the storyline for the Mystrious 'trilogy', at the time, went:
<div>Sophie ⟶ Firis ⟶ Lydie & Suelle (L&S)</div>
Sophie 2 slots in between the first two titles, so it chronologically occurs before the events of Firis. Being a direct sequel, it's natural to assume that playing the original Sophie is a prerequisite to play Sophie 2, but that's not really the case.
<ol>
<li class='list'>Sophie 1 is somewhat outdated</li>
If you want the full ugliness, curl the page and you’ll see what I mean. Writing articles was ugly.
I had to heavily rely on Vim plugins to help wrap elements with proper tags,
indents for figures in nested lists in paragraphs in subheadings in headings got ever more complicated to handle,
and half of the drafting process was just syntax checking.
I made lots of grammar errors because I had to pay attention to HTML tags instead of focusing on writing.
I also made some big template changes as time passed. If I updated one file, all the other files in the webserver had to be updated individually. The best I could do is use a convoluted Vim macro, but manual intervention was often required because not all files were written equally. For instance, I wrote a macro to update the navigation bar at the top of every page, but blog posts had different bars than reviews and the blog posts themselves had different spacing, which caused the macro to fail. I proceeded to manually edit HTML headers for the next 30 minutes, which was a waste of time. It was tiring, I wanted automation and just wanted to focus on writing. The solution from day one was a SSG, which I didn’t know about at the time.
Initially, I started this webpage as an afternoon afterthought project;
something to hide the ugly 404 error when visiting https://jbox.me.
I didn’t know of SSGs, I didn’t even know how regular HTML worked back then.
So as I started writing and learning HTML,
I encountered SSGs and only realized how useful they would be when I already had over 20 lengthy handcrafted HTML files.
Looking at SSGs
Around two weeks ago, I started looking for a SSG to replace my self-inflicted pain. Since this was my first time trying such a program, I decided to go with Hugo. It has active development, lots of support and resources to look through, was known for its speed, and has good reputation. The concept of SSGs sounded fantastic; you just do the content writing and all the formatting and HTML assembling will be done for you. You can modularize your webpages and change parts of every page within a few seconds by updating a template, and there are plugins to extend the generator; SSGs solved all the problems I caused by manually writing HTML.
Although, one problem of Hugo (and really all SSGs) that bugged me were the themes. Take a look through them and see what you think. I don’t like most of them personally, the majority look rather similar and are very… bland? The available themes share the same layouts and similar designs, not something I like. No offense to any hard working maintainers for these themes, but I preferred my custom template used before migrating. Using one of the pre-made templates would have helped me start fast, but I don’t think I could have adapted and significantly change how I do my writing.
As I have learned many times in the past, the best way to do something is often to do it yourself. So, I followed that rule and built a rather janky Hugo theme. It’s very specialized for my use case so I doubt anyone else would be interested in using it, and I made this over a few nights while learning Go templating from scratch so it’s built poorly. But it works, and that’s good enough for me. I’ll gradually improve the theme as time passes to fix problems.
First thoughts
Learning and using Hugo has brought some incredible benefits, directly and indirectly. I definitely should have used an SSG from the very beginning instead of doing an abrupt midway transition.
Markdown is really great
I actually didn’t know how Markdown worked before using Hugo. After learning the super basics of Hugo, I immediately realized how great Markdown is. Using Markdown for writing was a gamechanger, I can’t emphasize how much better it is to write in Markdown instead of using HTML. It’s very nice, I’m probably going to use it for any computer note taking from here on. Markdown syntax is so darn simple and it provides about 90% of the functionality you’ll need when writing webpages. Using Markdown allows me to do more grammar checks, ignificantly reduces the syntax cluttering HTML brings, and is more pleasant to write in.
Hugo provides great features
Automatic rendering and refresh
Hugo provides an extremely useful automatic reloading feature where the webpage is re-rendered everytime you make a change to it and save. I have the Markdown file on one monitor, the rendered HTML on another and don’t have to manually refresh the page. I just look to my side and instantly see the applied changes, it’s very convenient and provides functionality that bulky IDEs would provide.
Enabling a proper production environment
When I had my old HTML setup,
I didn’t run a webserver on the computer and so the webserver’s root directory would be translated
to the system’s root directory.
This messed up HTML links, since /css_file now referred to a CSS file in the system’s root directory.
Since Hugo can essentially run as a local webserver,
I can now work with CSS and all links properly working while drafting. Nice.
Batch edit files with modular parts
The automatic rebuilding of all pages is extremely nice,
this is a significant benefit that Hugo has provided.
If I wanted to make a navigation bar change to all pages,
I just change header.html and Hugo does the work for me.
Repeat with the footer or any other part of the document.
I don’t need to tell Hugo to rebuild everything, it’s all done automatically.
Once I’m done and ready to publish the edited pages,
I just run one command to publish and then update a git repo to deploy everything.
This workflow makes me feel like a semi-legitimate web dev or power user, which is rather amusing.
Table of Contents
I’ve wanted to implement ToCs for a while and have been asked a few times, and now Hugo allows me to now implement them seamlessly. Inserting ToCs manually was just not happening due to the sheer work involved even with boilerplate files, but now it takes zero effort. Hugo automatically generates a ToC, you just need to configure where it should go and how it should be styled.
Tags and Categories
There are some features I haven’t experimented yet: tags and categories. Many SSG-made sites have these features, a good example is a recipe site. You can assign certain tags and categories to a content file and Hugo automatically creates a list page where pages with the same tags can be viewed. These may be helpful, but at my scale I don’t know if they’ll be that useful. Maybe if I have hundreds of articles, but that’s a long way off. Soon I’ll have to slow down my publishing pace otherwise I’ll (1) run out of topics, (2) get burnt out, or (3) destroy my eyes.
Some downsides
Hugo has been really great so far. I’m never going back to writing HTML by hand and learning SSGs is genuinely useful. However, there are some problems I’ve run into. There aren’t all Hugo’s fault, a combination of Markdown and my lack of knowledge is involved.
The biggest example is the change to the blog and review index pages layout. Ideally, I want to replicate the original look but that will require some more advanced Go templating and restructuring of how I organize my files. It’s not impossible to fix and I think the current view is decent, but I do somewhat miss the absolute control I had with bare HTML files.
Another downside is the loss of control due to Markdown’s limited scope. Markdown was designed for simple plain text formatting, yet can’t underline or highlight text. Hugo’s implementation of Markdown doesn’t support super/subscripts either, so I have to use some HTML in the middle of some articles which looks off. If I want tables with some cells spanning multiple rows, I again need to use raw HTML in the middle of the file which looks especially bad. These problems occur rarely, but are nuisances when they show up.
Mobile formatting is something I’m going to improve. I’m testing different layouts but it’s a bit rough to implement with my current knowledge of CSS. I recommend you use a computer to browse even if these problems weren’t present, but I will fix mobile layouts regardless. There are also odd formatting issues here and there, such as code blocks being a little hard to apply CSS to and therefore looking ugly. Ultimately, these are caused by templated structures and me trying to fight against them. I’ll learn more about how to tweak themes and get along with Hugo, after that the website should be in peak form.
Summary
Hugo is a rather mature project and a very capable SSG, my work is a humble demonstration of its potential. If I were more advanced, I could use better Go templating to build a better website, but that’ll come later on. I’m going to continue see what I can do with Hugo, it has revolutionized my workflow and I want to see what else I can improve on the site. By using a SSG, my site is now much more scalable and robust to future changes. Maybe I can do some spell checking now instead of having to worry about not properly closing HTML tags.