Skip to content

Commit

Permalink
Update archetypes and glossary
Browse files Browse the repository at this point in the history
  • Loading branch information
@jmooring
jmooring authored Aug 24, 2023
1 parent 1a4522b commit ed35fc6
Show file tree
Hide file tree
Showing 2 changed files with 154 additions and 44 deletions.
177 changes: 136 additions & 41 deletions content/en/content-management/archetypes.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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 content`.
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 content` command uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetypes, 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 >}}

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 above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these:
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

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

The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example.
Archetypes receive the following objects and values in [context]:

## Create a new archetype template
- `.Date`
- `.Type`
- `.Site` (see [details](/variables/site/))
- `.File` (see [details](/variables/files/))

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.
As shown above, the default archetype passes `.File.ContentBaseName` as the argument to the `replace` function when populating the title in front matter.

{{< code file="archetypes/newsletter.md" >}}
## 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 >}}
---
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.

## New cool posts
## Signature

{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }}
* {{ .Title }}
{{ end }}
```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.
{{< /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

```bash
hugo new content newsletter/the-latest-cool.stuff.md
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.

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&nbsp;`.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.

The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo&#39;s template funcs can be used in the archetype file.
To create a new gallery:
```text
hugo new galleries/bryce-canyon
```

## Directory based archetypes
This produces:

Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory:
```text
content/
├── galleries/
│ └── bryce-canyon/
│ ├── images/
│ │ └── .gitkeep
│ └── index.md
└── _index.md
```

## Use alternate archetype

```bash
archetypes
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:

```text
archetypes/
├── articles.md
├── default.md
└── post-bundle
├── bio.md
├── images
│ └── featured.jpg
└── index.md
└── tutorials.md
```

```bash
hugo new content --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
21 changes: 18 additions & 3 deletions content/en/getting-started/glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ See [template action](#template-action).

### archetype

A template to create new content. See [details](/content-management/archetypes/).
A template for new content. See [details](/content-management/archetypes/).

### argument

Expand All @@ -36,6 +36,14 @@ See [boolean](#boolean).

A data type with two possible values, either `true` or `false`.

### branch bundle

A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/).

### build

To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.

### bundle

See [page bundle](#page-bundle).
Expand Down Expand Up @@ -100,11 +108,14 @@ See [page kind](#page-kind).

See [template](#template).

### leaf bundle

A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/).

### localization

Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.


### map

An unordered group of elements, each indexed by a unique key. See the [Go&nbsp;documentation](https://go.dev/ref/spec#Map_types) for details.
Expand All @@ -123,7 +134,7 @@ A data structure with or without associated [methods](#method).

### page bundle

A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles, leaf and branch. See [details](/content-management/page-bundles/).
A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](/getting-started/glossary/#leaf-bundle) and [branch bundles](/getting-started/glossary/#branch-bundle). See [details](/content-management/page-bundles/).

### page kind

Expand Down Expand Up @@ -163,6 +174,10 @@ Within a [template action](#template-action), a pipeline is a possibly chained s

A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go&nbsp;documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.

### publish

See [build](#build).

### render hook

A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/).
Expand Down

0 comments on commit ed35fc6

Please sign in to comment.