Hugo and the Mainroad Theme

I think I’ve found the ideal theme for my Hugo site. Mainroad is relatively simple in design, the layout is roughly what I was looking for, and it’s easier to customise. It still has tags and categories features that are essential for a site hosting technical documentation. I spent around six hours learning how the template works, re-arranging the content and tweaking the CSS to make it as clean as my MkDocs site. It looks just as good on mobile devices.

Top-Level Pages and Content

There are two subdirectories to create in /content, as per the example site: /docs and /post. The /docs subdirectory is where the top-level pages are stored, and the frontmatter for each determines where the links to those pages are in the navigation menu. e.g.

---
title: Martial Arts
description: Information about martial arts, primarily Aikido
authorbox: false
sidebar: false
menu:
  main:
    name: Martial Arts
    weight: 4
---

Change the menu -> main -> weight value to change the order of items in the main navigation menu.

The /post subdirectory is where we place the Markdown files for whatever blog posts we want to publish. The site works better without an index.md file in /content, as the initial view will be a list of the most recent blog posts instead of top-level pages.

CSS

Next is the CSS. I used the in-browser developer tools to find the element/rule names then changed them in the existing style.css file within the theme directory. I made the site header smaller, applied my own colour scheme, increased the margin between the header and page titles and the line spacing… That sort of thing. Just to make the site appear cleaner.

Embedding images in posts is a little tricky. At first I scaled the images in an image editor, since there was no obvious way to do it with Markdown or HTML in Hugo. I later found it’s possible to embed HTML using ‘shortcodes’, e.g.

Entire blocks of HTML markup can be placed between shortcodes for opening and closing root elements.