I’ve lost count how many times I’ve rebooted my personal blog. As is tradition, I’m going to dedicate the first post to documenting how it’s setup so I can diagnose and fix things when I break everything a couple months down the road.

Installation and Configuration

This site is built in Hugo, which at the time of this writing (May 2020) seems to be the most popular static site generator outside of Gatsby, which I found to be overly complicated for my purposes. I avoided Hugo for a long time, but once I finally caved in it turned out that installation was pretty straightforward. I installed Homebrew in my WSL and from there installing Hugo was a single line:

# Install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

# Install Hugo
brew install hugo

Creating the new blog was the following line, which created all of the necessary elements in a new directory blog.dwgill.com. I then proceeded to create a git repo in that directory.

hugo new site blog.dwgill.com
cd blog.dwgill.com
git init
git add --all
git commit -m "initial commit"

I found a custom theme for the blog and added it to the repo as a submodule.

git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng

Because I know I will forget how to update this theme with upstream changes, here’s the relevant documentation and the command itself:

git submodule update --remote themes/hello-friend-ng

The theme I’m using includes [an example config][]. I recorded my initial draft of changes to this configuration for later reference. I thought it would be neat to have a dynamic rotating text for the header. I dug into the html of the theme and found out it references a customJS parameter. Any URL placed here will be appended to the body of each page of the website. For example, I could add jQuery to each page with the following:

customJS = ["https://cdnjs.cloudflare.com/ajax/libs/jquery/3.5.1/jquery.min.js"]

As it is, I just want a little bit of JavaScript to swap out the header text, so really what I’m looking for is to create a new file, serve that file from the blog itself, and then reference this file in the config itself. So, I created the following JavaScript file:

(function () {
  var logoTexts = [
    'tea, earl grey, hot',
    'hello world',
    'roll for initiative',
    'rm -rf /',
  ];

  var randomText = logoTexts[Math.floor(Math.random() * logoTexts.length)];

  document.querySelector('.logo .logo__text').textContent = randomText;
})();

I added this file to the /static/ directory of the repo under the name dynamic-header.js and then added this line to the config file:

customJS = ["/dynamic-header.js"]

This works because any file placed in the /static/ directory of your Hugo site is automatically served off of the root of your site’s URL. So it’s fine if the browser encounters a script tag like the following:

<script src="/dynamic-header.js"></script>

This is fine, because Hugo is actually serving the file at http://blog.dwgill.com/dynamic-header.js.

Using Hugo

Run a local dev server:

# Does not show draft posts
hugo server
# Does show draft posts
hugo server -D

Add a new post:

hugo new posts/post-title.md

Build the site

# Without drafts
hugo

# With drafts
hugo -D

Deployment

With all the above in order, I commited and pushed everything to a private Github repository. From there, I went to [Netlify][] and created a new site from the Github project. It recognized immediately that it was a Hugo site and correctly guessed both command to build the site as well as where the site’s output files would be placed. The only snag was getting the domain name blog.dwgill.com setup correctly.

I own the dwgill.com domain through Hover, and have no complaints about the service. For various reasons, however, I actually delegate the management of this domain to Digital Ocean as I like to be able to easily point subdomains (e.g. foo.dwgill.com) at new virtual private servers I spin up on a whim. However, as mentioned above, I’m hosting this blog on Netlify, not Digial Ocean. (I use Digital Ocean for web servers and applications, not static sites.) As a result, there’s a further level of indirection as I have to configure Digital Ocean to point the blog.dwgill.com subdomain at my Netlify application. Netlify maintains its own domain for the app at dwgill-blog.netlify.app, so the result is that I need to configure blog.dwgill.com on Digital Ocean to point at dwgill-blog.netlify.app on Netlify, while at the same time Netlify needs to be aware that blog.dwgill.com points at it.

Digital Ocean domain config

Digital Ocean domain config

Netlify domain config

Netlify domain config

Once this is all configured, the blog is automatically deployed whenever I push changes to the master branch of that aforementioned Github repo.