Moving to Hugo

22 Dec, 2020

My original Jekyll-based site stopped working for some reason. Rather than try to figure out what was going on with it, I decided to try out some alternative site generators. I’d heard about Hugo a bit so I decided to give it a try. The other thing I’d been meaning to do is start posting about all the various tech things I’ve been working on, as well as interesting talks I’ve seen, papers I’ve read, and that sort of thing. One of the things people tell you as a grad student is to write/post/publish as much as you can, so heck, I’ll give it a try. One thing I like about this system is that the build tool outputs content into a different repo. This makes it easier for me to work with. Here’s a basic walkthrough of the process to setup a similar site:

Install Hugo

I’m on a Mac so this is pretty easy using Homebrew:

$ brew install hugo

Since Hugo is a Go binary you should be able to just download it and run it though.

Create the scaffolding for your project

Hugo generates most of this stuff for you. I decided to name my project webpage:

$ hugo new site webpage
Congratulations! Your new Hugo site is created in /Users/petewilcox/git/webpage.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Hugo will create the directory structure and some starter files. Next up is to install a theme, I’m using Hugo ʕ•ᴥ•ʔ Bear Blog because it’s very simple:

$ cd webpage
$ git init
Initialized empty Git repository in /Users/petewilcox/git/webpage/.git/
$ git submodule add                                 \
    https://github.com/janraasch/hugo-bearblog.git  \
    themes/hugo-bearblog
Cloning into '/Users/petewilcox/git/webpage/themes/hugo-bearblog'...
remote: Enumerating objects: 6, done.
remote: Counting objects: 100% (6/6), done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 351 (delta 0), reused 1 (delta 0), pack-reused 345
Receiving objects: 100% (351/351), 196.29 KiB | 2.84 MiB/s, done.
Resolving deltas: 100% (168/168), done.

So now we’ve got the Hugo framework and a theme installed, what next? As the Bear Blog docs say:

If you are starting fresh, simply copy over the contents of the exampleSite-directory included in this theme to your source directory. That should give you a good idea about how things work, and then you can go on from there to make the site your own.

$ cp -r themes/hugo-bearblog/exampleSite/ .

And now we’re setup to start configuring out site.

Edit site config

Earlier we copied over the config.toml from the theme into the root of the repo. Now we’ll open that up and set it up for our site. I’m not sure if this is actually necessary but I edited these:

baseURL
title
author
description
favicon
images

Note that for the last two, the images should be placed in the static directory.

Configure image floats

I wanted to be able to have image floats but didn’t want to screw around with HTML too much since I’m not a front end developer at all. I searched around a bit and found this blog post which had the CSS code we need:

img[src$='#center']
{
    display: block;
    margin: 0.7rem auto; /* you can replace the vertical '0.7rem' by
                            whatever floats your boat, but keep the
                            horizontal 'auto' for this to work */
    /* whatever else styles you fancy here */
}

img[src$='#floatleft']
{
    float:left;
    margin: 0.7rem;      /* this margin is totally up to you */
    /* whatever else styles you fancy here */
}

img[src$='#floatright']
{
    float:right;
    margin: 0.7rem;      /* this margin is totally up to you */
    /* whatever else styles you fancy here */
}

The file themes/hugo-bearblog/layouts/partials/style.html contains the CSS code used for the site and by just adding this in we can then add image floats like this:

![your_img](/img/your_img.png#center)
![your_img](/img/your_img.png#floatleft)
![your_img](/img/your_img.png#floatright)

Create some content

At this point we’re ready to start writing some pages. For individual pages (like my Research page for instance) we can do:

$ hugo new research.md
/Users/petewilcox/git/webpage/content/research.md created

For blog posts we’ll do:

$ hugo new blog/somepost.md
/Users/petewilcox/git/webpage/content/blog/somepost.md created

In either case Hugo will generate some template info:

---
title: "Somepost"
date: 2020-12-23T01:16:31-08:00
draft: true
---

The block in between the --- delimiters (what Hugo calls Front Matter) tells Hugo how to place this content, what to name it, that sort of thing. draft: true tells Hugo that this page is a draft, so don’t publish it in production. What we want to do is have our main pages added to the main menu, and the rest of it added to blog posts. So our main pages will look like:

---
title: "Research"
date: 2020-12-23T01:16:31-08:00
menu: "main"
---

Our blog posts will look like:

---
title: "Some Blog Post"
date: 2020-12-23T01:16:31-08:00
---

This will put the research page in the main menu (at the top of the site) and the blog post will be added to the list automatically generated on the blog page.

Add a favicon

Take some picture and feed it into a favicon generator (I used this one). Put the resulting favicon.ico and favicon-32x32.png into the static directory and make sure they match your settings in config.toml.

Create a project repo

Go to GitHub and make a new empty repo for your Hugo project. Once it’s created, copy the repo url and add it to your project:

$ git remote add origin [email protected]:pcwilcox/webpage.git

Host a site on a custom domain

This part is pretty easy and is done in three steps:

Get a domain name. I got mine from Namecheap for about $12 a year.
Setup a GitHub repo to host the site. Note that this is different from the project repo we set up before. In the settings for the repo, scroll down in the Options section to GitHub Pages to activate web hosting.
Following the instructions, go to your DNS provider (I use Cloudflare) and create a CNAME record to point to the GitHub page. For mine I created an entry which points www.pcwilcox.com to pcwilcox.github.io.

Setup deployment

We’ll follow the Hugo docs here and setup a script to deploy the public directory to the GitHub pages repo automatically. First, make sure your page is all setup the way you want it. Remove the drafts = true line from the front matter sections. Run hugo once to make sure it builds without errors, check the public directory and make sure everything is ok. Once it is, remove the public directory. We’ll add the site as a submodule:

$ git submodule add -b main [email protected]:pcwilcox/pcwilcox.github.io public

Next we’ll setup the script to automate deployments:

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin main

Important note here, running deploy.sh updates the public website repo, but not your project repo. You’ll need to do that separately.

All done!

And that’s it, run the script ./deploy.sh <commit message> and it’ll build the server and deploy it to GitHub.

#setup #walkthrough #blogging #hugo