Background

This project is built with Hugo and uses the Minimal Hugo theme.

This post is part of an ongoing effort to tailor the theme over time.

After working with Hugo for a while you might find that there are certain pieces of code that you include in every project.

Once you tire of manually copying and pasting them, it’s time to figure out which template file to alter to automatically include those snippets.

Because Hugo offers so much flexibility and produces pages in such a layered way, it can be difficult to find the right place to make the necessary alterations.

This project recently required such a search to figure out how to include two pieces of code that were routinely added to the source files for posts.

The first inclusion was a comment field at the top of the document to help track the date of post creation:

<!--
    POST CREATION
        date: 2022-03-14T09:00
-->

The second was also a comment field, but at the bottom of the document to help organize links from the page:

<!-- LINKS -->

Neither are big additions, but it’s obviously better to add them automatically instead of re-typing them manually each time.

What change to make and where to make it

Figuring out how and where to add those snippets took some research and experimentation.

After reading and testing, the best option appeared to be copying the post.md file from the

• hugo-project-directory/themes/theme-name/archetypes directory

to the

• hugo-project-directory/archetypes directory

and then modifying this new post.md file.

After identifying the right place to make the change, the change itself was pretty simple.

hugo-project-directory/archetypes/post.md:

---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
description: ""
tags: [""]
draft: true
---

<!--
    POST CREATION
        date: {{ .Date }}
-->

Hello, World!

<!-- LINKS -->

The desired text was added directly to the template and the special {{ .Date }} shortcode was added so that Hugo would automatically supply the current datetime at the time of file creation.

Understanding the change

While the “what” and “where” of the change was established by experimentation, the “why” wasn’t immediately obvious.

As is often the case, the clearest source for information on how to work with Hugo can be found in Mike Dane’s Hugo Tutorial video series. In this case specifically, his video on Hugo Archetypes clarified what Hugo is doing.

In short, when creating a new file, Hugo first looks for a template with a name matching the directory containing that new file, and, importantly, files in the project archetypes directory take precedence over those in the themes directory.

Not complicated, but also not obvious.