DE

Hugo Archetypes: Create Content Quickly and Template-Based

The standard installation of Hugo comes with a command-line tool to create new content based on templates. In official terminology, these templates are referred to as archetypes. With their help, files are automatically filled with relevant information so that writers can more quickly turn to the actual content.

As templates, archetypes are comparable to layouts, and the same template actions can be used. Their main purpose is to create the front matter. This distinguishes them from layouts, which are generally the better choice for standardizable content.

A command-line tool is used to create one new page. In the simplest case, one Markdown file is created, which is the focus of this article. It can also be used to create so-called page bundles—directories that represent a single page. We will also look at this option later on.

The tool can also be used to create a new Hugo website or a new Hugo theme. As these uses are fairly self-explanatory, they are not discussed in this article.

Using the Tool

The tool for creating content is executed from the root directory of the website. The command follows the following pattern:

hugo new content [flags] [path]

As mentioned at the beginning, the new files are filled with content based on templates. The so-called archetypes are defined in Markdown format and stored under archetypes/.

Similar to layouts, archetypes are applied automatically. The first path component (the top-level section) is crucial: If there is an archetype of the same name, the new content is created based on this template.

Archetypes also work at lower levels of the directory structure. If archetypes/blog.md exists, it will be used in the following example:

hugo new content blog/2024/post-1.md

Unfortunately, archetypes cannot be tailored to content as specifically as layouts can. Perhaps you would expect to be able to create archetypes/blog/list.md or archetypes/blog/_index.md to be uses for _index files under blog/. However, the lookup order for archetypes is much simpler.

We can follow the same structure as for layouts, but we must explicitly select the archetype to be used. To do this, we can use the --kind flag:

hugo new content --kind blog/list blog/2024/_index.md

In fact, we can use any archetypes in this way. To create a more predictable system, it is advisable to apply the same structure as you would for layouts.

If no suitable archetype is found or defined, Hugo creates the new content based on a default archetype, which is defined under archetypes/default.md.

Use Cases

In archetypes, {{ ... }} expressions can be used, just like in layouts. In their context, four pieces of information are readily available:

  • The current time (in RFC3339 format)
  • Information about the file to be created (such as the file name)
  • The type resulting from the first path component or the --kind option
  • The object that represents the entire website and from which information can be retrieved using predefined methods

With this data, many of the typical requirements can be easily implemented.

Publication Date

The official documentation recommends to include the publication date in the front matter of each page. In principle, this information can be taken directly from the context:

date: '{{ .Date }}'

However, the return value of the Date method is very precise and would look something like this: '2023-08-24T11:49:46-07:00'. If you prefer a simpler representation, you can convert the value into a different format using time.Now. For most purposes, a date without a time should be sufficient:

date: '{{ time.Now.Format "2006-01-02" }}'

Publication Status

We probably don’t want to immediately publish the content we have just created. In Hugo, this is achieved by declaring it to be a draft, which is why the corresponding front-matter field is a typical component of archetypes:

draft: true

When the work on the page was completed, the field can be removed.

Other fields relate to the publication status. With publishDate you can define the date from which a page is available on the website. Conversely, expiryDate can be used to define a date from which the page will no longer be accessible. Archetypes for certain types of content can make use of these fields, for example to publish new blog posts on the next following Wednesday.

Title

The title is the second piece of meta information that should be included in every front matter. As mentioned above, the name of the file to be created is available in the context. So, in order to get the title, we can replace - or _ with spaces and then convert the resulting string into the so-called Title Case using the built-in title function.

title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'

This would turn to-kill-a-mockingbird.md into a file in which title has the value 'To Kill a Mockingbird'.

There is not one Title Case. Different styles agree that you would capitalize the first and last word, and all verbs, nouns, pronouns, and adjectives. Prepositions with four or more letters, however, may be capitalized, depending on the Title Case Style. The default is capitalization in accordance with the Associated Press Stylebook, while the Chicago Manual of Style recommends lowercase for all prepositions.

titleCaseStyle can be set in the main configuration, with ap, chicago and go being the most important options.

# Use Chicago Manual of Style rules instead of AP.
# Generally, fewer prepositions are capitalized.
# See: https://titleformat.com/posts/ap-vs-chicago-title-case/
titleCaseStyle: 'chicago'

Archetypes for Page Bundles

So far, files have been created with the command line tool. As mentioned in the introduction, the tool can also be used to create directories. More precisely, it can be used to create directories that stand for one single page (so-called Leaf Bundles). Note that archetypes are not intended for entire sections (Branch Bundles).

Page bundles of this kind are essentially directories that contain an index.md and zero or more other files and subdirectories. The template expressions can be used for the index file and any other markup files it may contain, as with file archetypes. All other files are copied one-to-one to the target directory.

The official documentation gives an example where an archetype with index.md and an images/ subdirectory is created under layouts/galleries/. This archetype is used to create a page bundle:

hugo new galleries/bryce-canyon

This results in a directory under content/galleries/bryce-canyon, which contains the same files and subdirectories as the template and whose index.md has been processed like an ordinary archetype.

As with file archetypes, this can also be used to create page bundles at lower levels of the directory structure. The following command would create the exact same directory two levels deeper:

hugo new galleries/a/b/bryce-canyon

As before, the first path component determines which archetype is used. And again, the --kind flag can be used to specifically select the archetype to be used.

hugo new --kind other-archetype galleries/a/b/bryce-canyon

The result of this command would again be the directory under content/galleries/a/b/bryce-canyon. However, the contents of this new directory are derived from the contents of archetypes/other-archetype/.

Article from October 12, 2024.