What are Archetypes?
Archetypes are content files in the archetypes directory of your project that contain preconfigured front matter for your website’s content types. Archetypes facilitate consistent metadata across your website content and allow content authors to quickly generate instances of a content type via the
hugo new command.
hugo new generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command:
hugo new <content-section>/<file-name.md>
We can use this pattern to create a new
.md file in the
hugo new posts/my-first-post.md
Running this command in a new site that does not have default or custom archetypes will create the following file:
+++ date = "2017-02-01T19:20:04-07:00" title = "my first post" draft = true +++
The auto-populated fields are worth examining:
titleis generated from the new content’s filename (i.e. in this case,
"my first post")
titleare the variables that ship with Hugo and are therefore included in all content files created with the Hugo CLI.
dateis generated in RFC 3339 format by way of Go’s
now()function, which returns the current time.
- The third variable,
draft = true, is not inherited by your default or custom archetypes but is included in Hugo’s automatically scaffolded
default.mdarchetype for convenience.
Three variables per content file are often not enough for effective content management of larger websites. Luckily, Hugo provides a simple mechanism for extending the number of variables through custom archetypes, as well as default archetypes to keep content creation DRY.
Lookup Order for Archetypes
Similar to the lookup order for templates in your
layouts directory, Hugo looks for a section- or type-specific archetype, then a default archetype, and finally an internal archetype that ships with Hugo. For example, Hugo will look for an archetype for
content/posts/my-first-post.md in the following order:
hugo new site)
Choose Your Archetype’s Front Matter Format
hugo new content files include front matter in the TOML format regardless of the format used in
You can specify a different default format in your site configuration file file using the
metaDataFormat directive. Possible values are
Default archetypes are convenient if your content’s front matter stays consistent across multiple content sections.
Create the Default Archetype
When you create a new Hugo project using
hugo new site, you’ll notice that Hugo has already scaffolded a file at
The following examples are from a site that’s using
categories as taxonomies. If we assume that all content files will require these two key-values, we can create a
default.md archetype that extends Hugo’s base archetype. In this example, we are including “golang” and “hugo” as tags and “web development” as a category.
+++ tags = ["golang", "hugo"] categories = ["web development"] +++
Use the Default Archetype
archetypes/default.md in place, we can use the CLI to create a new post in the
posts content section:
$ hugo new posts/my-new-post.md
Hugo then creates a new markdown file with the following front matter:
+++ categories = ["web development"] date = "2017-02-01T19:20:04-07:00" tags = ["golang", "hugo"] title = "my new post" +++
We see that the
date key-values have been added in addition to the
categories key-values from
Suppose your site’s
posts section requires more sophisticated front matter than what has been specified in
archetypes/default.md. You can create a custom archetype for your posts at
archetypes/posts.md that includes the full set of front matter to be added to the two default archetypes fields.
Create a Custom Archetype
+++ description = "" tags = "" categories = "" +++
Use a Custom Archetype
archetypes/posts.md in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the
posts content section:
$ hugo new posts/post-from-custom.md
This time, Hugo recognizes our custom
archetypes/posts.md archetype and uses it instead of
archetypes/default.md. The generated file will now include the full list of front matter parameters, as well as the base archetype’s
+++ categories = "" date = 2017-02-13T17:24:43-08:00 description = "" tags = "" title = "post from custom archetype" +++
Hugo Docs Custom Archetype
As an example of archetypes in practice, the following is the
functions archetype from the Hugo docs:
--- linktitle: "" description: "" godocref: "" publishdate: "" lastmod: "" categories: [functions] tags:  ns: "" signature:  workson:  hugoversion: "" aliases:  relatedfuncs:  toc: false deprecated: false ---