From ed35fc6c47604e485d41aba5ad971f548d85d9a2 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Thu, 24 Aug 2023 16:23:58 -0700 Subject: [PATCH] Update archetypes and glossary --- content/en/content-management/archetypes.md | 177 +++++++++++++++----- content/en/getting-started/glossary.md | 21 ++- 2 files changed, 154 insertions(+), 44 deletions(-) diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index 99a6a4e89..d811bbac2 100644 --- a/content/en/content-management/archetypes.md +++ b/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 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 ``` -The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: +With the default archetype shown above, Hugo creates this content file: -1. `archetypes/posts.md` -2. `archetypes/default.md` -3. `themes/my-theme/archetypes/posts.md` -4. `themes/my-theme/archetypes/default.md` +{{< 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 >}} -The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. +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: -## Create a new archetype template +```text +archetypes/ +├── default.md +└── posts.md +``` -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. +## Lookup order -{{< code file="archetypes/newsletter.md" >}} +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]: + +- `.Date` +- `.Type` +- `.Site` (see [details](/variables/site/)) +- `.File` (see [details](/variables/files/)) + +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 >}} --- -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: -## New cool posts +`someFunction` returns the string `s` repeated `n` times. -{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} -* {{ .Title }} -{{ end }} +## 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. {{< /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. -```bash -hugo new content newsletter/the-latest-cool.stuff.md +## 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. + +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. -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. +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 +``` -```bash -archetypes +## 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: + +```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: -[archetypes directory]: /getting-started/directory-structure/ -[content types]: /content-management/types/ -[front matter]: /content-management/front-matter/ +```text +hugo new content --kind tutorials articles/something.md +``` + +[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 diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md index 8b3fd4ee2..40cb30c75 100644 --- a/content/en/getting-started/glossary.md +++ b/content/en/getting-started/glossary.md @@ -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 @@ -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). @@ -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 documentation](https://go.dev/ref/spec#Map_types) for details. @@ -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 @@ -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 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/).