Posting with Hugo

Creating new posts and managing content with Hugo took a little thought/experimentation to get the flow I wanted. Firstly, I needed to get rid of the default TOML rubbish and secondly I needed to get my head around a sensible way of managing basic data.

Creating and Editing Pages

Pages are created with the hugo new command:

hugo new articles/tech/posting-with-hugo.md

This creates a new file on that path with a base template in place. Files contain Front Matter which is the meta data that defines how the page works, then the content is either assumed from the file extension i.e. .md is markdown, or from the front matter configuration.

I’m editing my articles in VSCode, using the Markdown format and a split pane with a Markdown preview. In the VSCode terminal, I have the development hugo server running with live reloading (hugo server -D) with my local site open in Chrome. So every time I hit ctrl-s I get a preview for real in the browser. Pretty nice and also techie. So I’m happy 😃!

Changes are made, committed to git and pushed up to BitBucket.

Archetypes and Front Matter

New articles are created from templates known as Archetypes. You can create as many archetypes as you need, to make sure when you create a new page/post/article it’s set up how you want. The archetypes can be part of the theme, or in the base Hugo install.

The Goa theme I started with has a horrible (to me) base TOML default archetype:

+++ 
draft = false 
comments = false 
slug = "" 
tags = []
categories = []

showpagemeta = true
showcomments = true
+++

This caused me a little confusion at first as I didn’t understand why I was getting a different blank article to the examples in the quick start. I added a new default archetype directly in Hugo, so that would be used going forward. This lives in the archetypes folder in the base of my site (personal-site\archetypes) it’s called default.md and is now used every time I create a new page:

{
    "draft": true,  
    "title": "{{ replace .Name "-" " " | title }}",
    "description": "SUMMARY.",
    "date": "{{ .Date }}",
    "tags": [],
    "categories": []
}

This means all pages are now JSON configuration, the title defaults to the slug I used when creating the page and the date defaults to the date and time I ran the command. Brilliant:

hugo new articles/tech/posting-with-hugo.md

Gives me:

{
    "draft": true,
    "title": "Posting With Hugo",
    "description": "SUMMARY.",
    "date": "2021-10-10T14:16:28+01:00",
    "tags": [],
    "categories": []
}

Shared Settings

There are a whole bunch of options you can configure in the Front Matter that I’d like on some defaults for all articles, which may not be the Hugo defaults e.g. turning the integrated comments off. And I want to be able to change my mind later and not have to script a bulk update to all my JSON.

Fortunately, at any folder level you can add a _index.md file which can have a cascade block for front matter options to apply to all children. So in my articles\_index.md I have set up my options:

{
    "title": "Articles",
    "cascade": {
        "comments": false,
        "showpagemeta": true,
        "showcomments": false
    }
}

Great! That index file can also be used to put content into the list page for a category/section. My theme didn’t render anything from that, so I’ve tweaked the li.html file in the theme to include the title and any content if it’s there. Which means I can put an intro into any list I want.

By default, I’ve also realised that Hugo lists posts by an optional weight meta-item, then by various other items. This means I can add weight to my Hugo posts, an intro in the _index.md and have them appear in a logical order rather than the order I published them!

Publishing Cycle

So there we go, with a little work on my archetypes and _index.md I can now add a new page with a single Hugo command that gives me a good start for the page. Write it, preview it in the browser. git commit as I go, and when I’m ready, turn it from "draft": "true" to "draft": "false", push changes to git, build the site with hugo --minify and then upload the public folder to my web-host.

Nice. The site is screamingly fast and pleasingly “techie” to work on.