setting up a lean mean hugo blogging theme

November 10, 2022

When I first started messing around with hugo, I found the whole thing slihtly mystifying. I downloaded a theme like they asked me, edited the config file to try and customise things a little and quickly broke everything. To be fair, this was mainly due to my tinkering instinct to fly to close to the sun. But anyway, the point at which I started to really appreciate the power of hugo was when I tried to make my own - admittedly less feautureful - theme. This selection of tips and tricks will assume that you’ve just run something like hugo new site lovely-new-website, entered the new directory with cd lovely-new-website and you’ve got a selection of mostly empty directories looking something like this.

.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── public
├── static
└── themes

Our first concern will be getting a barebones theme template that can be customised to our liking. I would recommend this guy which I used to get up and running. You could also check out my theme which I’m using on this site that is also very simple (as you can probably see from the website lol). Once you’ve got a theme with (I’m using mine as an example) git clone https://gitlab.com/robbygozzarder/mcl and placed it in the themes directory you’ll need to adjust your config.toml file to point it to this theme.

theme="mcl"

The directory structure of your new theme will look something like this:

.
└── mcl
    ├── archetypes
    │   └── default.md
    ├── layouts
    │   ├── 404.html
    │   ├── _default
    │   │   ├── list.html
    │   │   └── single.html
    │   ├── index.html
    │   └── partials
    │       ├── footer.html
    │       ├── header.html
    │       └── nav.html
    ├── README.md
    └── static
        └── css
            └── style.css

This is where most of the magic happens:

The default.md file in the archetypes directory dictates what template to follow when adding new post files.
The layouts directory is where most of the meat is:
- Firstly, there’s the partials directory which contains outlines for sections which you want to be used multiple times across the site such as a footer (footer.html)
- Sceondly, we have _default which contains outlines for the two types of hugo pages; singles (single.html) such as this individual post page, and lists (list.html) such as the tags and posts pages on this site.
- Partials also contains index.html which (you guessed it!) is your home page.
Last but not least, there’s static which as you can see just has the css for the site (this is all looks though - the action happens in partials).

Now the theme is sorted the next three things you need to know anything about (imho) are the content, public, and static directories:

Content is where you put your posts - these are just markdown files which hugo converts to html for you.
Public is where hugo puts your built - ready to be served - site. You can then copy this directory to wherever your webserver is looking eg. /var/www/jdysmcl
Static is where assets which you want to use with your site are kept. I basically just use it for images which I can then reference from my posts.

Now we’ve got the directory what’s happening where admin out the way let’s have a look at what some of the html files in the themes directory look like; this is the index.html for my site for example:

{{ partial "header.html" . }}

<p>This is mainly a place for me to document various
bits and bobs I've been doing on my computers.
I am a noob in most things so take anything written
here with a pinch of salt. Lots of love :)</p>

{{ .Content }}
{{ range .Site.RegularPages | first 5 }}
  <h3> <a href="{{ .RelPermalink }}">{{ .Title }}</a></h3>
  {{ .Summary }}
  <br><br>
  {{ .Date.Format "06 Jan, 2006" }} |
  {{ .WordCount }} words |
  {{ .ReadingTime }} mins |

  {{ range (.GetTerms "tags") }}
    <a href='{{ .Permalink }}'>{{ .LinkTitle }}</a>
  {{ end }}

{{ end }}

{{ partial "footer.html" . }}

In short, this plops the header and footer partials at the top and bottom of the page respectively, includes a short warning not to listen to me, and then displays my five most recent posts along with a snippet of the post and some accompanyning info: date, word count, reading time, and tags. The keen eyed among you will have noticed that this is a mish mash of normal html tags and strange stuff enclosed in double curly brackets. I’m going to end on this cliffhanger but if you want to know more about the curly brackets check out the hugo docs here.