Archetypes
Overview
A content file consists of front matter and markup. The markup is typically markdown, but Hugo also supports other content formats. Front matter can be TOML, YAML, or JSON.
The hugo new content
command creates a new file in the content
directory, using an archetype as a template. This is the default archetype:
---
date: '{{ .Date }}'
draft: true
title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
---
+++
date = '{{ .Date }}'
draft = true
title = '{{ replace .File.ContentBaseName `-` ` ` | title }}'
+++
{
"date": "{{ .Date }}",
"draft": true,
"title": "{{ replace .File.ContentBaseName `-` ` ` | title }}"
}
When you create new content, Hugo evaluates the template actions within the archetype. For example:
hugo new content posts/my-first-post.md
With the default archetype shown above, Hugo creates this content file:
---
date: "2023-08-24T11:49:46-07:00"
draft: true
title: My First Post
---
+++
date = '2023-08-24T11:49:46-07:00'
draft = true
title = 'My First Post'
+++
{
"date": "2023-08-24T11:49:46-07:00",
"draft": true,
"title": "My First Post"
}
You can create an archetype for one or more content types. For example, use one archetype for posts, and use the default archetype for everything else:
archetypes/
├── default.md
└── posts.md
Lookup order
Hugo looks for archetypes in the archetypes
directory in the root of your project, falling back to the archetypes
directory in themes or installed modules. An archetype for a specific content type takes precedence over the default archetype.
For example, with this command:
hugo new content posts/my-first-post.md
The archetype lookup order is:
- archetypes/posts.md
- archetypes/default.md
- themes/my-theme/archetypes/posts.md
- themes/my-theme/archetypes/default.md
If none of these exists, Hugo uses a built-in default archetype.
Functions and context
You can use any template function within an archetype. As shown above, the default archetype uses the replace
function to replace hyphens with spaces when populating the title in front matter.
Archetypes receive the following objects and values in context:
As shown above, the default archetype passes .File.ContentBaseName
as the argument to the replace
function when populating the title in front matter.
Include content
Although typically used as a front matter template, you can also use an archetype to populate content.
For example, in a documentation site you might have a section (content type) for functions. Every page within this section should follow the same format: a brief description, the function signature, examples, and notes. We can pre-populate the page to remind content authors of the standard format.
---
date: '{{ .Date }}'
draft: true
title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
---
A brief description of what the function does, using simple present tense in the third person singular form. For example:
`someFunction` returns the string `s` repeated `n` times.
## Signature
```text
func someFunction(s string, n int) string
```
## Examples
One or more practical examples, each within a fenced code block.
## Notes
Additional information to clarify as needed.
Although you can include template actions within the content body, remember that Hugo evaluates these once—at the time of content creation. In most cases, place template actions in a template where Hugo evaluates the actions every time you build the site.
Leaf bundles
You can also create archetypes for leaf bundles.
For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images.
Create an archetype for galleries:
archetypes/
├── galleries/
│ ├── images/
│ │ └── .gitkeep
│ └── index.md <-- same format as default.md
└── default.md
Subdirectories within an archetype must contain at least one file. Without a file, Hugo will not create the subdirectory when you create new content. The name and size of the file are irrelevant. The example above includes a .gitkeep
file, an empty file commonly used to preserve otherwise empty directories in a Git repository.
To create a new gallery:
hugo new galleries/bryce-canyon
This produces:
content/
├── galleries/
│ └── bryce-canyon/
│ ├── images/
│ │ └── .gitkeep
│ └── index.md
└── _index.md
Use alternate archetype
Use the --kind
command line flag to specify an alternate archetype when creating content.
For example, let’s say your site has two sections: articles and tutorials. Create an archetype for each content type:
archetypes/
├── articles.md
├── default.md
└── tutorials.md
To create an article using the articles archetype:
hugo new content articles/something.md
To create an article using the tutorials archetype:
hugo new content --kind tutorials articles/something.md