Moving to Hugo

It’s been a long time since I started using the ox-tufte exporter to keep and maintain my website. However, I have had issues with it; one of the larger ones being that it’s a pain in the butt to remember how it all works when I want to change the structure of it.

I also was a little tired of the look and layout; being presented with an endless table of contents isn’t the best experience one could hope for online.

Not to worry, I am in the midst of migrating most of my writing to Hugo!

Naturally, since I am a lover of prose and dearly enamored with sidenotes, I opted for the hugo-tufte theme. However, I immediately found some unpleasantness in it.

While I can and do appreciate whitespace, there is such a thing as too much. So I spent a number of hours fixing up the CSS (and a few minor things) more to my liking. at the same time, I realized that there are some limitations.

I won’t bore you with the details, suffice to say I forked the repo and started messing with it. I’m not familiar or even remotely good with CSS/ HTML/ Hugo, so please don’t expect miracles(1) (1)Also called ‘clean code.’ .

Most of my changes were minor; color scheme adjustments, decreasing the massive margins between the elements, getting some styling on the margin and side notes, and such.

One thing that I realized quickly was that the way sidenotes are implemented leads to them overlapping when they’re close together; I have yet to find a solution for that, so for the time being, I am choosing to simply make the sidenote font smaller so they don’t.

Other than that… I’m really happy with it.

Of course, I didn’t stop there. Being the crazy person that I am, I wanted to automate deployment of my website through git.

And so I did. You can find the repo here. The important bit lies on the server side.

I’m using a git hook to automatically purge and re-build the /public directory after each commit. I don’t get enough traffic for this to be an inconvenience.

I used some of this article by Jason Murray to help me understand how git hooks work. I’m running Forgejo, and this is a much more elegant and simple solution when compared to running Actions or other CI/CD tools.

The post-receive hook is like so:

#!/bin/bash
# Directory on the server where the website will be mapped.
export GIT_WORK_TREE=/srv/bajsicki.com

echo `pwd`
echo "post-receive: Generating https://bajsicki.com with Hugo..."

# Create the directory and all subdirectories if they don't exist.
mkdir -p $GIT_WORK_TREE
chmod 755 $GIT_WORK_TREE

# Remove any files already in the public directory, a fresh copy will be generated by hugo
rm -rf $GIT_WORK_TREE/public

# Generate the site with hugo
cd $GIT_WORK_TREE && chmod +x update.sh
cd $GIT_WORK_TREE && ./update.sh

# Fix any permission problems.
find $GIT_WORK_TREE/public -type f -print | xargs -d '\n' chmod 644
find $GIT_WORK_TREE/public -type d -print | xargs -d '\n' chmod 755

echo "post-receive: Hugo site generation complete"

The update.sh script is as dead simple as things get.

#!/usr/bin/env sh

cd themes/hugo-tufte/
git reset --hard && git pull origin main -f
cd ../..
git reset --hard && git pull origin main -f
hugo

In short… it just works, and I can easily transition my blogging/ websites to Hugo without compromising on my org-mode addiction.

All thanks to ox-hugo, which made the process very easy, since I already had all of my articles in org-mode format in the first place.

I guess the last thing to mention are the sidenotes and margin notes… sadly, the way to use them with ox-hugo is quite cumbersome. My current process is to keep these two snippets in the kill-ring(2) (2)I will be moving them to yasnippet… at some point. , so I can easily insert them when needed.

@@hugo:{{<sidenote>}}
{{</sidenote>}}@@

Then an example of it would look like this(3) (3)Or maybe not, I’m not sure. .

@@hugo:{{<sidenote>}}Or maybe not, I'm not sure.{{</sidenote>}}@@

The same formatting applies to marginnote.

As you may notice, there is an issue. For some reason the hugo-tufte theme doesn’t treat the sidenote number/ indicator as only a character, but adds a whitespace after it as well. This can lead to some hanging punctuation, so if you see that on this website, that’s why. And if you don’t, there’s a tiny chance I fixed it.

Still, all things considered, I am quite happy, and working on this website has been a great reprieve from bombarding my brain with infosec.

Join the FSF.