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:

1. archetypes/posts.md
2. archetypes/default.md
3. themes/my-theme/archetypes/posts.md
4. 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:

• Date
• Type
• File
• Site

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