Migrating to Hugo Apéro

September 4, 2021

howto

Hugo, blog, blogdown

I just migrated my personal site from the overwhelming Hugo Academic theme to the much lighter yet still very functional Hugo Apéro theme by Alison Hill.

I feel like a lot of potential friction has been removed, and the path is now cleared for me to focus on generating content, which after all is the whole point of this site.

My issue with the Hugo Academic theme #

First, I’ll start by saying that I think the Academic theme is an excellent Hugo theme. I’ve seen some impressive sites built with the Academic theme. It is extremely feature rich and configurable. It’s just not for me.

Academic’s functionality and configurability are actually my biggest issues with the theme. I found myself spending way too much time tinkering with code, configurations, and parameters. This really cut into my time focusing on writing and producing interesting work. Academic’s feature set became a distraction.

Academic included too many features that I don’t think I will ever use. The concept of modular widgets and all the extra niceties are great, but I simply didn’t need most of it. All those features were actually detractors for me.

Why I like the Hugo Apéro theme #

When I set out to pick a Hugo theme, I had a number of considerations laid out:

It had to be fairly popular and well-maintained. I checked for this by looking at the number of Github stars associated with each theme repository, as well as their commit histories.
It had to play nicely with Blogdown. I author this site using R and Blogdown, and wanted something that worked well with my core tools. Many Hugo themes were not designed with R and Blogdown in mind, and often led to compatibility problems.
It had to handle math. I’m a data scientist, and sooner or later, I expect that I’ll be writing math here on data science topics. Being able to write math in some sort of *TeX would be super handy.
It had to be fairly minimal. I wasn’t interested in spending too much time trying to figure things out with a theme. If there were too many files or too many lines of code in the base theme, it was out.
It couldn’t be too minimal. A lot of the super minimal Hugo themes start with nothing more than some blog, about, and tag sections. I wanted simple, but I also wanted to leave myself some room to grow, including into things like a hero section or work portfolios.
It had to be visually appealing right out of the box with minimal work. This is a fairly subjective point. I wanted something that looked easy to read, like a book almost.

The Apéro theme met all of those conditions. The fact that the package’s primary author is also affiliated with RStudio and is a contributor to the Blogdown package itself was a big plus.

Getting started with Hugo Apéro #

It took me less than an hour to get my site set up with Apéro, with everything configured to an acceptable state. Most of that time was spent poking at different options in the config.yaml file and getting the structure of the /content directory laid out.

The series of steps I took on day 1 with Apéro included:

Installation - From within RStudio, I started a new Blogdown project with the Hugo theme setting pointed at hugo-apero/hugo-apero. Once this was done, I had the skeleton of a Apéro site laid out.
Migration - This is honestly a bit of a hack job, but since my existing site with the Academic theme was so sparse, I decided the simplest approach to handling the theme migration was to delete all the folders and files within my site’s working git repository, and then copy in all the files from the newly-generate project. The only pieces I kept were the posts and pages I had authored (there were only four, and not all of them had been made public yet), the .git directory, and the netlify.toml file. This ensured that all the machinations I had previously figured out with linking my Github repository to Netlify for deployment wouldn’t break. Silvia Canelón has a much more elegant way of handling the migration from Academic to Apéro.
Modify config.yaml - The config.yaml within the site’s root directory controls pretty much all the major settings for the theme. That includes things like titles, colors, fonts, menus, and more. I simply went down the file line by line and added, modified, or deleted values as appropriate. This was a fairly straightforward and painless task. By the end of this step, the site pretty much looked the way I wanted it to look. The Apéro documentation covers this extremely well.
Purge content - The initial state of a clean Apéro install includes some sample content, which serves as a great reference. But it’s not my content, and I don’t need to work with all of that material at the start. That includes things like projects or talks. I simply deleted it all, leaving only the pieces within /content/about, /content/blog/_index.md, and license.md. There is also a great set of reference material contained within /themes/exampleSite/content, so all is not lost.
Port posts - I copied my previously written posts into the /content/blog directory, and that was it as far as moving posts was concerned. This is probably one of the most appealing things about using a static site generator like Hugo. Everything is simply written in Markdown (or Rmarkdown), and that written content is contained within a sensible directory structure. When it comes time to make any migrations, it’s embarrassingly easy to move the content.
Modify blog - The /content/blog/_index.md controls how the blog main page and the individual blog posts appear. This includes things like the blog page layout (list, list with a sidebar, or grid), labels, bylines, and metadata like dates. There are also options under cascade that control how elements within individual blog posts appear. The Apéro documentation again covers this extremely well.
Modify about - The /content/about path contains all the material related to the About section. /content/about/header/index.md controls the header, /content/about/main/index.md controls the main body, and /content/about/sidebar.index.md controls the sidebar. /content/about/sidebar/avatar.jpg (or whatever you choose the rename it to) can be used with a simple headshot or any other image you so choose to appear in the sidebar.
Create a Resources page - In Hugo, everything is treated as a page. I started off knowing that I wanted a Resources page to track the different materials I’ve learned from. To create this page, I created a /content/resources directory, and placed an index.md file there. The lower section of the file contained all the written material in Markdown, and the top of the file included some top-matter that defined different attributes of the page. If I ever create any additional one-pagers in the future, they’ll essentially follow this format.

---
description: Here's a listing of all the various forms of content that I have found useful for my learning.
draft: false
# layout: standard # commented out so the content did not consume the full width of the page
show_title_as_headline: true
title: Resources
---

And that’s about it. Eventually, I would like to put together a portfolio and a talks section, but that’s a task for another day.

Parting thoughts #

Hopefully, with this theme transition, I will actually be more consistent with producing content.

I’m already in the habit of taking fairly copious (i.e., rambling) notes using other tools, including a mix of Markdown files and Google Docs. Instead of keeping all that to myself and in a very rough state, my plan is to instead clean and curate all that material and drop it into my site so it’s actually readable and useful content.

Feel free to hold me accountable if months from now, you find that the content coming out here is nothing more than a trickle.