diff options
Diffstat (limited to 'docs/content/en/content-management/archetypes.md')
| -rw-r--r-- | docs/content/en/content-management/archetypes.md | 183 |
1 files changed, 139 insertions, 44 deletions
diff --git a/docs/content/en/content-management/archetypes.md b/docs/content/en/content-management/archetypes.md index d8c864536..d811bbac2 100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@ -1,6 +1,6 @@ --- title: Archetypes -description: Archetypes are templates used when creating new content. +description: An archetype is a template for new content. keywords: [archetypes,generators,metadata,front matter] categories: [content management] menu: @@ -13,78 +13,173 @@ weight: 140 aliases: [/content/archetypes/] --- -## What are archetypes? +## Overview -**Archetypes** are content template files in the [archetypes directory] of your project that contain preconfigured [front matter] and possibly also a content disposition for your website's [content types]. These will be used when you run `hugo new`. +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: -The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme. +{{< code-toggle file="archetypes/default.md" copy=false fm=true >}} +title = '{{ replace .File.ContentBaseName `-` ` ` | title }}' +date = '{{ .Date }}' +draft = true +{{< /code-toggle >}} -{{< code file="archetype-example.sh" >}} -hugo new posts/my-first-post.md -{{< /code >}} +When you create new content, Hugo evaluates the [template actions] within the archetype. For example: + +```text +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: + +```text +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: + +```text +hugo new content posts/my-first-post.md +``` + +The archetype lookup order is: + +1. archetypes/posts.md +1. archetypes/default.md +1. themes/my-theme/archetypes/posts.md +1. 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`](/functions/replace/) function to replace hyphens with spaces when populating the title in front matter. + +Archetypes receive the following objects and values in [context]: -The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: +- `.Date` +- `.Type` +- `.Site` (see [details](/variables/site/)) +- `.File` (see [details](/variables/files/)) -1. `archetypes/posts.md` -2. `archetypes/default.md` -3. `themes/my-theme/archetypes/posts.md` -4. `themes/my-theme/archetypes/default.md` +As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter. -The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. +## Include content -## Create a new archetype template +Although typically used as a front matter template, you can also use an archetype to populate content. -A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor. +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/newsletter.md" >}} + +{{< code file="archetypes/functions.md" copy=false >}} --- -title: "{{ replace .Name "-" " " | title }}" -date: {{ .Date }} +date: '{{ .Date }}' draft: true +title: '{{ replace .File.ContentBaseName `-` ` ` | title }}' --- -**Insert Lead paragraph here.** +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. -## New cool posts +## Notes -{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} -* {{ .Title }} -{{ end }} +Additional information to clarify as needed. {{< /code >}} -When you create a new newsletter with: +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](/getting-started/glossary/#build) the site. + +## Leaf bundles + +You can also create archetypes for [leaf bundles](/getting-started/glossary/#leaf-bundle). + +For example, in a photography site you might have a section (content type) for galleries. Each gallery is leaf bundle with content and images. -```bash -hugo new newsletter/the-latest-cool.stuff.md +Create an archetype for galleries: + +```text +archetypes/ +├── galleries/ +│ ├── images/ +│ │ └── .gitkeep +│ └── index.md <-- same format as default.md +└── default.md ``` -It will create a new newsletter type of content file based on the archetype template. +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. + -**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites. +To create a new gallery: +```text +hugo new galleries/bryce-canyon +``` -The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo's template funcs can be used in the archetype file. +This produces: + +```text +content/ +├── galleries/ +│ └── bryce-canyon/ +│ ├── images/ +│ │ └── .gitkeep +│ └── index.md +└── _index.md +``` -## Directory based archetypes +## Use alternate archetype -Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory: +Use the `--kind` command line flag to specify an alternate archetype when creating content. -```bash -archetypes +For example, let's say your site has two sections: articles and tutorials. Create an archetype for each content type: + +```text +archetypes/ +├── articles.md ├── default.md -└── post-bundle - ├── bio.md - ├── images - │ └── featured.jpg - └── index.md +└── tutorials.md ``` -```bash -hugo new --kind post-bundle posts/my-post +To create an article using the articles archetype: + +```text +hugo new content articles/something.md ``` -Will create a new folder in `/content/posts/my-post` with the same set of files as in the `post-bundle` archetypes folder. All content files (`index.md` etc.) can contain template logic, and will receive the correct `.Site` for the content's language. +To create an article using the tutorials archetype: + +```text +hugo new content --kind tutorials articles/something.md +``` -[archetypes directory]: /getting-started/directory-structure/ -[content types]: /content-management/types/ -[front matter]: /content-management/front-matter/ +[content formats]: /getting-started/glossary/#content-format +[content types]: /getting-started/glossary/#content-type +[context]: /getting-started/glossary/#context +[front matter]: /getting-started/glossary/#front-matter +[template actions]: /getting-started/glossary/#template-action +[template]: /getting-started/glossary/#template +[template function]: /getting-started/glossary/#function |