![Bjørn Erik Pedersen](/assets/img/avatar_default.png)
cb18a5183 Fix broken link 07a0198bf Config: Place Google Analytics tag ID under the services key 4bf0c719f Fix typo 50d8ad1af Fix muiltilingual menu definition instructions 1a32519a9 Fix typos 6f34ca8e0 Explain usage of front matter to target a template 5bd977257 Improve goldmark config docs 447632938 Remove Docker notes from installation instructions 84741d173 Update reference to hugo.work 0338d7c71 Fix menu template f5d2f5ed4 Fix typos in content/en/functions/fmt a3a40ff99 Add return type to functions 85ac3e779 Remove outdated feature image d47d889e4 Fix signatures 7551ba28f Document safe.JSStr function e77993be0 Document keyVals function 4dba20db3 Update theme babf91544 Update echoparam 8c8203efa Adjust related functions 4cb1b30fc Fix example ba95eca64 Improve showcase prose 5d3dcf366 Add Overmind Studios showcase 8d634ac70 Change code blocks from indented to fenced cfab978e6 Add missing code fences 407dd5c47 Limit related pages for functions to other functions 9fa67d981 Fix .Site.LastChange doc 393aa16d0 netlify: Hugo 0.119.0 f864af97a docs: Even more about images.Process 9d772d5f0 docs: More about images.Process bc655f869 docs: Regen docshelper 41c3536d1 Merge commit '9aec42c5452b3eb224888c50ba1c3f3b68a447e9' 918ed53f4 Add images.Process filter 573645883 Add $image.Process a1151b0fd Add images.Opacity filter git-subtree-dir: docs git-subtree-split: cb18a5183fc62f301ffde50b8c39f03e4b897aec
5.8 KiB
title | description | keywords | categories | menu | toc | weight | aliases | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Archetypes | An archetype is a template for new content. |
|
|
|
true | 140 |
|
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:
{{< code-toggle file="archetypes/default.md" copy=false fm=true >}}
title = '{{ replace .File.ContentBaseName -
| title }}'
date = '{{ .Date }}'
draft = true
{{< /code-toggle >}}
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:
{{< code-toggle file="content/posts/my-first-post.md" copy=false fm=true >}} title = 'My First Post' date = '2023-08-24T11:49:46-07:00' draft = true {{< /code-toggle >}}
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.
{{< code file="archetypes/functions.md" copy=false >}}
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
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. {{< /code >}}
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