Maximizing the convenience factor: archetypes in Hugo

By Bryce Wray

There are many reasons why static site generators (SSGs) have become so popular, especially in recent years. The reason which seems to come up most often is that SSG-based sites have superior performance and security, which certainly is true enough.

However, theres another key advantage that probably doesnt get nearly the attention it deserves: the convenience SSGs provide.

When used properly, SSGs can automate many of the tasks involved in building and maintaining a website. This capability, which becomes increasingly important as the site grows in size and complexity, reduces the need to concentrate on some of the more mundane aspects of website work. As a result, web developers and their clients have more time and freedom to make better decisions about websites content, performance, and design the things that will most effectively satisfy current visitors and attract new visitors.

Similarly, web devs often praise Hugo for its admittedly awesome build speed, yet overlook how Hugo is packed with features designed specifically to provide category-leading convenience to both developers and site owners. In this article, well try to make at least some headway in correcting that oversight, as we take a closer look at Hugos archetypes.

Archetypes in general

To begin with: what exactly is an archetype, Hugos use of the term aside?

According to dictionary.com, the word archetype means: The original pattern of model from which all things of the same kind are copied or on which they are based; a model or first form; [a] prototype.

Think of a cookie-cutter. With cookie dough and a cookie-cutter thats shaped like a gingerbread man, youll end up with gingerbread-man cookies. That cookie-cutters shape was the archetype for the shape of each cookie.

Or consider what often happens in the process of developing salespeople. Training courses designed and led by a particularly successful sales professional will likely produce graduates who sell in a manner very similar to that of the trainer who, at least in this sense, has served as those trainees archetype.

Archetypes in Hugo: the basics

Now, lets get back to Hugo.

As you probably know, much of what any SSG brings to the table depends heavily on templating. Many web developers remember all too well a time when they had to hand-code even large websites one page at a time. They can richly appreciate how much better it is just to create a relatively small number of templates and let an SSG do the rest. Thats doubly true with Hugo, given its astounding site-building velocity during both development and production.

But what has that to do with archetypes? Perhaps we can put it this way: not every Hugo template is an archetype, but every Hugo archetype is a template and a special kind of template, at that.

To quote the Hugo documentation: Archetypes are templates used when creating new content. Lets dig more deeply into that explanation.

If youve ever run hugo new site to create a (you guessed it) new Hugo site, you know that one of the default folders in the resulting project is archetypes/, which contains a single file, default.md. In that file, youll find only the following front matter:

    ---    title: "{{ replace .Name "-" " " | title }}    date: {{ .Date }}    draft: true    ---

This is the sites default archetype, which Hugo will apply whenever you use hugo new to create a content file in your Hugo project.

In case youre not familiar with the templating that Hugo uses, heres what the front matters curly-bracketed items tell Hugo to do:

• Convert the file name into title case and make that the files title.
• Assign the files creation date/time to the files date.
• Make this file a draft meaning that Hugo, by default, wont convert it to a page during either development or production. (Keep that in mind for later.)

So, if you run hugo new my-article.md at 2:37:20 PM U.S. Central Daylight Time (CDT) on April 7, 2022, Hugo creates content/my-article.md with the following front matter:

    ---    title: "My Article"    date: 2022-04-07T14:37:20-05:00    draft: true    ---

Again: thats only the bare, default behavior. Theres so much more you can do with Hugo archetypes.

Customizing archetypes for your project

You can already see that the use of Hugo commands and variables allows even the default archetype to accomplish a lot, but lets do more than just scratch the surface. No two Hugo projects are the same, so their archetypes neednt be, either.

Before we get to examples, we should understand how Hugo determines which archetype it will assign to a specific content file. As noted, if a project has only the original default archetype, Hugo will use that one for any content you create with hugo new, but we clearly arent going to stop there.

Lets say you and your client, XYZ Company, have decided on a website whose Hugo project will have the following general content structure:

    .     content         about-us         blog         contact-us         products         support

Lets say also that XYZ Company diligently keeps its websites Support section updated for both consumers and dealers, perhaps with a Hugo structure like this:

    .     content         support             consumers                 docs                 downloads                 faq                     alpha-widgets                     gamma-widgets             dealers                 docs                     manuals                     parts-lists                     tech-updates                 downloads             security-alerts

And well further say that the Support Department requires each FAQ content file to adhere to a naming convention of either alpha-nnn.md or gamma-nnn.md, wherein the alpha or gamma refers to one of the companys two major product lines (Alpha Widgets and Gamma Widgets) and the nnn is a three-digit identifier number. For example, a file named alpha-029.md would be the content for FAQ page number 29 for the Alpha Widgets FAQ section.

Oh, theres one more thing: the clients previous web developer, using a totally different set of code and for reasons no one seems to remember now, set the site so that a file named alpha-029.md has a URL of xyzcompany.com/support/consumers/faq/alpha-widgets/029/ and the client requires not only that such URLs remain the same but also that future FAQ content files produce the same results. URL redirects are a no-go, and the Support Department refuses to change the long-time convention for Markdown file names.

It sounds a bit hairy, but all of this constitutes a perfect scenario for customized Hugo archetypes.

Looking at our content/support/ structure example above, lets create an archetype for just the Consumer FAQ section at archetypes/faq.md, with the following front matter (any content after #, or wrapped inside {{/*</code> and <code>*/}}, is a comment):

    {{/*- The following vars assume three-digit FAQ #s -*/}}    {{- $faqNo := substr .Name -3 -}}    {{- $prod := substr .Name 0 -4 -}}    {{- $prodName := $prod | title -}}    ---    title: "{{ $prodName }} Widgets - FAQ #{{ $faqNo }} | XYZ Company Consumer FAQ"    date: {{ .Date }}    draft: true    type: support/consumers/faq    # To make page go live when site is built,    # change `draft` to false (no quot. marks)    author: "" # Fill in    slug: "{{ $prod }}-widgets/{{ $faqNo }}/"product: "{{ $prodName }} Widgets"    featured_image: "/images/featured/for-faq/{{ $prod }}.jpg"    featured_image_alt: "Image of XYZ Company's {{ $prodName }} Widgets product"    featured_image_credit: "Image: John Doe Photography for XYZ Company."    ---

What does all the Hugo code do? Lets break it down, with alpha-029.md as the first file well create from the archetype.

First, above the front matters top --- delimiter, were creating three variables for later use in several places below:

• $faqNo is the last three characters adhering to the nnn convention of the content files name; e.g., 029.
• $prod is that file name without the -nnn part of the name; e.g., just alpha.
• $prodName is $prod converted to nice, neat title case; e.g., Alpha.

From there, we get the date/time (.Date) of the files creation, as in Hugos default archetype, and then we use type to tell Hugo which layout to use (if necessary, refer to our earlier article, The Ultimate Guide to Hugo Sections).

Remember the clients requirement about the URL? We meet it with the slug line. While a Hugo URL usually is based strictly on where a content file is located, using slug overrides that. Thus, in this example, content/support/customers/faq/alpha-029.md will produce the desired URL of xyzcompany.com/support/customers/faq/alpha-widgets/029/ (i.e., rather than xyzcompany.com/support/customers/faq/alpha-029/, as Hugo normally would do it).

Still, dont try hugo new just yet. Theres one more thing to address.

With all those nested levels, how do you make sure which archetype the hugo new command will use? Unlike how layouts work in Hugo, having an identically nested level of archetypes isnt the way to do it. The answer is to add a --kind (or -k) flag to the hugo new command. In this case, we want Hugo to know that this file will be of the faq content kind. This ensures that, regardless of how deeply nested the resulting file will be within the project, itll start from the correct archetype.

So, with the archetypes/faq.md file set as described above, the command to use will be:

    hugo new support/consumers/faq/alpha-029.md --kind faq

This tells Hugo, Build a new Markdown file called alpha-029.md, using the archetype file at archetypes/faq.md because this new file is of the faq kind, and put it in the projects content/support/consumers/faq/ folder.

By entering that command at 7:31:32 AM CDT on April 29, 2022, youll get content/support/consumers/faq/alpha-029.md, complete with the following front matter:

    ---    title: "Alpha Widgets - FAQ #29 | XYZ Company Consumer FAQ"    date: 2022-04-29T07:31:32-05:00    draft: true    type: support/consumers/faq    # To make page go live when site is built,    # change `draft` to false (no quot. marks)    author: "" # Fill in    slug: "alpha-widgets/029/"    product: "Alpha Widgets"    featured_image: "/images/featured/for-faq/alpha.jpg"    featured_image_alt: "Image of XYZ Company's Alpha Widgets product"    featured_image_credit: "Image: John Doe Photography for XYZ Company."

. . . and, because of the use of slug, the resulting web pages URL will be xyzcompany.com/support/consumers/faq/alpha-widgets/029/, as the client wants.

Pretty slick, eh? Wait. It gets better.

Directories can be archetypes

Hugos directory-based archetypes that is, directories which themselves are archetypes enable you to build new site structures more quickly. In fact, it may be worth your while to keep one or more such directories in archetypes/ for those times when the client wants a major site expansion, and wants it yesterday.

Lets say your archetypes/ folder looks like this:

    .     archetypes         blogpost.md         changelog.md         default.md         faq.md         tech-update.md         z-bundle             _index.md             a                 _index.md                 z-a.md             b                 _index.md                 z-b.md             c                 _index.md                 z-c.md             d                 _index.md                 z-d.md             e                 _index.md                 z-e.md

Notice the z-bundle folder with five sub-folders, each with an _index.md archetype and a non-index archetype.

In this example, XYZ Company has just acquired UVW Company and suddenly wants you to add a new top-level section, xyzcompany.com/uvw/, featuring the former competitors products. To get a quicker start on this process, run hugo new uvw --kind z-bundle . This will result in content/uvw/, arranged as shown:

    .     content         uvw             _index.md             a                 _index.md                 z-a.md             b                 _index.md                 z-b.md             c                 _index.md                 z-c.md             d                 _index.md                 z-d.md             e                 _index.md                 z-e.md

You then can easily rename folders and files accordingly, of course, but this is much simpler than creating everything one folder at a time and one file at a time. As this new part of the project grows, you even can use this capability to create still deeper nested levels, such as with hugo new uvw/sublevel --kind z-bundle to get:

    .     content         uvw             _index.md             a                 _index.md                 z-a.md             b                 _index.md                 z-b.md             c                 _index.md                 z-c.md             d                 _index.md                 z-d.md             e                 _index.md                 z-e.md             sublevel                 _index.md                 a                     _index.md                     z-a.md                 b                     _index.md                     z-b.md                 c                     _index.md                     z-c.md                 d                     _index.md                     z-d.md                 e                     _index.md                     z-e.md

You can repeat this to keep building downward, as far as needed.

Pitfalls to avoid

Weve spent the article up to now singing the praises of Hugo archetypes, but you also should be aware that there are a couple of potential gotchas in using them. Lets now discuss those.

Do you know your draft status?

This first item actually is not so much a failing of Hugo archetypes as it is something thats true of Hugo content creation in general. Those who begin playing with archetypes often use just hugo new to experiment with what archetypes generate, only to become frustrated when Hugo doesnt use the resulting file even though they can clearly see that its where it should be.

The problem, more often than not, is the fact that the default archetype and, because people tend to copy and paste from it, a number of other archetypes that get built has draft: true in its front matter.

Whoops.

Always remember that Hugos default behavior in both development and production modes is to ignore such files when building the site. Its a feature, not a bug.

Your client may be perfectly happy if archetypes dont create draft files by default, so thats an option you may want to suggest; but, in a worst-case scenario, you or the client might publish some content that wasnt truly ready. Sometimes, draft: true can be ones friend.

Watch the extensions

Any file whose name ends with .md, .markdown, or .goldmark (the latter refers to the name of the Markdown parser that Hugo uses) is a legitimate Markdown content file as far as Hugo is concerned. However, that doesnt mean you can use those interchangeably when building archetypes.

For one thing: as of this writing, Hugo doesnt allow the use of a .goldmark file as an archetype, although you can manually create a .goldmark file in content/ and Hugo will recognize it.

As for .md and .markdown, you must make sure youre matching archetype extension with destination-file extension. Suppose you create the file archetypes/tester.md. The following wont work as you expect:

    hugo new tester.markdown --kind tester

If you happen to have an archetype file at archetypes/default.markdown, this command will result in a content/tester.markdown file, all right, but itll be based on the default.markdown archetype rather than the tester.md archetype.

In short: keep .md with .md, and .markdown with .markdown; and steer clear altogether of .goldmark, at least where Hugo archetypes are concerned.

Dont be your own arch-enemy

Many long-time Hugo users typically dont use archetypes to create content files, despite being aware of this feature. If youre in that group, perhaps this article has changed your mind on the subject.

(Its worth noting here that Hugo pages created within CloudCannon dont currently support the archetypes workflow, though if youre developing locally and syncing with CloudCannon for your content editors to do their work, you can still use archetypes to your hearts content. As of this articles publication date CloudCannon has a development project in the works to address this workflow within the app for all SSGs, including Hugo.)

Those coming to Hugo from other SSGs might have other ideas about creating new content files, often in the form of just copying and pasting from previous Markdown files front matter to start new files. That works, too, but its a much more manual process than what weve described herein. And remember: those other SSGs dont even have this archetypes feature to begin with, so they dont give you a choice in the matter. Hugo does.

Even if Hugo archetypes were only cookie-cutter copies, going back to our early analogy, theyd constitute an impressive time- and labor-saving device. But when you also take into account how Hugo archetypes can use logic to create file names, URLs, and much more on the fly not to mention how entire directories can be archetypes you see a higher level of convenience that only Hugo provides.

Hugo can be a powerful ally in your web development, but only to the extent that you learn about its capabilities, and take full advantage of them. In that sense, knowledge truly is power.