Archetypes in Hugo is a great way to make starting off a new page, blog post, or any other types of content. It is in essence a type template that makes it a little faster to create content by automatically generating a skeleton with pre-filled metadata and content to start you of. In my blog I use it to automatically differentiate between posts and other types of content. It took me a while to get me head around how this works, so I thought I would share how I think about this feature and hopefully it will help someone that thinks the same way as I do.
Every time you create a new content page using the hugo generator (hugo new) it will search your system for an archetype file that matches what you are generating. It will first search your archetype folder in your site, and if none is found there, it will search for one in your configured template. There is a gotcha here with precedence that I'll explain with an example.
First let's decompose the generator shell command.
$> hugo new post/post-name.md
│ │ │ │
│ │ │ └─ name of the content being generated
│ │ └─ type of the content being generated
│ └─ generator command to create new content
└─ hugo command
This will create a new file at content/post/post-name.md using the archetype for post. As you can see, the type is also added to the path of the content when it gets generated to easily identify which type a content page is. Hugo uses folders to infer types and taxonomy. This can be overridden in the the “Front Matter”, the metadata section at the begging of your files.
In my archetypes folder I have a file called post.md that I use as a template for all of my blog posts. It contains this:
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
author: "Thomas Winsnes"
description: "Insert description"
tags:
-
---
Write blog here
The section on the top between the two --- is the “Front Matter” and it is used to provide meta data about the post. In my case, the title, date it was written, tags etc. These values are used by Hugo to generate the html, and can be directly accessed by the theme. So as you can see it saves time and means you don't have to look up the names for your metadata value every time you create a new post.
The gotcha that I mentioned before, is about how Hugo selects which archetype file to use when generating a new content file. It uses the type that is inferred from the path, or if it's overridden in the “Front Matter” by setting type: typename.
When using the command above hugo new post/postname.md, it will look for the archetype in this order:
archetypes/post.mdarchetypes/default.mdthemes/<themename>/archetypes/post.mdthemes/<themename>/archetypes/default.md
As you can see, it will look for the file that matches the type name in your root archetypes folder first, and if it can't, it will look for one called default.md as a fallback. If it can't find either, it will then look in your registered theme archetypes folder. So if you're aiming to use the archetypes from a theme, make sure you don't have a default archetype in your root archetypes folder. This tripped me up when working with this the first time.
There area a lot of powerful things you can do with archetypes and front matters which I won't go into details on here, but the hugo documentation covers a lot of it.