blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-30 02:02:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revise the archetype docs

Browse Source 
Fixes #11
This commit is contained in:
Bjørn Erik Pedersen
2018-03-07 11:12:28 +01:00
parent 5d4c3c03c6
commit 7cfd530d24
2 changed files with 35 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/content-management/archetypes.md
+28 -144
View File
@@ -1,10 +1,9 @@
---
title: Archetypes
linktitle: Archetypes
description: Archetypes allow you to create new instances of content types and set default parameters from the command line.
description: Archetypes are templates used when creating new content.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: [archetypes,generators,metadata,front matter]
categories: ["content management"]
menu:
@@ -18,175 +17,60 @@ aliases: [/content/archetypes/]
toc: true
---
{{% note %}}
This section is outdated, see https://github.com/gohugoio/hugoDocs/issues/11
{{% /note %}}
{{% todo %}}
See above
{{% /todo %}}
## What are Archetypes?
**Archetypes** are content files in the [archetypes directory][] of your project that contain preconfigured [front matter][] for your website's [content types][]. Archetypes facilitate consistent metadata across your website content and allow content authors to quickly generate instances of a content type via the `hugo new` command.
**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`.
{{< youtube bcme8AzVh6o >}}
The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command:
```
hugo new <content-section>/<file-name.md>
```
We can use this pattern to create a new `.md` file in the `posts` section:
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 file="archetype-example.sh" >}}
hugo new posts/my-first-post.md
{{< /code >}}
{{% note "Override Content Type in a New File" %}}
To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
{{% /note %}}
Running this command in a new site that does not have default or custom archetypes will create the following file:
{{< output file="content/posts/my-first-post.md" >}}
+++
date = "2017-02-01T19:20:04-07:00"
title = "my first post"
draft = true
+++
{{< /output >}}
{{% note %}}
In this example, if you do not already have a `content/posts` directory, Hugo will create both `content/posts/` and `content/posts/my-first-post.md` for you.
{{% /note %}}
The auto-populated fields are worth examining:
* `title` is generated from the new content's filename (i.e. in this case, `my-first-post` becomes `"my first post"`)
* `date` and `title` are the variables that ship with Hugo and are therefore included in *all* content files created with the Hugo CLI. `date` is generated in [RFC 3339 format][] by way of Go's [`now()`][] function, which returns the current time.
* The third variable, `draft = true`, is *not* inherited by your default or custom archetypes but is included in Hugo's automatically scaffolded `default.md` archetype for convenience.
Three variables per content file are often not enough for effective content management of larger websites. Luckily, Hugo provides a simple mechanism for extending the number of variables through custom archetypes, as well as default archetypes to keep content creation DRY.
## Lookup Order for Archetypes
Similar to the [lookup order for templates][lookup] in your `layouts` directory, Hugo looks for a section- or type-specific archetype, then a default archetype, and finally an internal archetype that ships with Hugo. For example, Hugo will look for an archetype for `content/posts/my-first-post.md` in the following order:
The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these:
1. `archetypes/posts.md`
2. `archetypes/default.md`
3. `themes/<THEME>/archetypes/posts.md`
4. `themes/<THEME>/archetypes/default.md` (Auto-generated with `hugo new site`)
3. `themes/my-theme/posts.md`
4. `themes/my-theme/default.md`
{{% note "Using a Theme Archetype" %}}
If you wish to use archetypes that ship with a theme, the `theme` field must be specified in your [configuration file](/getting-started/configuration/).
{{% /note %}}
The last two list items is only applicable if you use a theme and it uses the `my-theme` theme name as an example.
## Choose Your Archetype's Front Matter Format
## Create a New Archetype Template
By default, `hugo new` content files include front matter in the TOML format regardless of the format used in `archetypes/*.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.
You can specify a different default format in your site [configuration file][] file using the `metaDataFormat` directive. Possible values are `toml`, `yaml`, and `json`.
{{< code file="archetypes/newsletter.md" >}}
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---
## Default Archetypes
**Insert Lead paragraph here.**
Default archetypes are convenient if your content's front matter stays consistent across multiple [content sections][sections].
### Create the Default Archetype
## New Cool Posts
When you create a new Hugo project using `hugo new site`, you'll notice that Hugo has already scaffolded a file at `archetypes/default.md`.
The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
{{< code file="archetypes/default.md" >}}
+++
tags = ["golang", "hugo"]
categories = ["web development"]
+++
{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }}
* {{ .Title }}
{{ end }}
{{< /code >}}
{{% warning "EOL Characters in Text Editors"%}}
If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.)
{{% /warning %}}
When you create a new newsletter with:
### Use the Default Archetype
```bash
hugo new newsletter/the-latest-cool.stuff.md
```
With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section:
It will create a new newsletter type of content file based on the archetype template.
{{< code file="new-post-from-default.sh" >}}
$ hugo new posts/my-new-post.md
{{< /code >}}
**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.
Hugo then creates a new markdown file with the following front matter:
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.
{{< output file="content/posts/my-new-post.md" >}}
+++
categories = ["web development"]
date = "2017-02-01T19:20:04-07:00"
tags = ["golang", "hugo"]
title = "my new post"
+++
{{< /output >}}
We see that the `title` and `date` key-values have been added in addition to the `tags` and `categories` key-values from `archetypes/default.md`.
{{% note "Ordering of Front Matter" %}}
You may notice that content files created with `hugo new` do not respect the order of the key-values specified in your archetype files. This is a [known issue](https://github.com/gohugoio/hugo/issues/452).
{{% /note %}}
## Custom Archetypes
Suppose your site's `posts` section requires more sophisticated front matter than what has been specified in `archetypes/default.md`. You can create a custom archetype for your posts at `archetypes/posts.md` that includes the full set of front matter to be added to the two default archetypes fields.
### Create a Custom Archetype
{{< code file="archetypes/posts.md">}}
+++
description = ""
tags = ""
categories = ""
+++
{{< /code >}}
### Use a Custom Archetype
With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section:
{{< code file="new-post-from-custom.sh" >}}
$ hugo new posts/post-from-custom.md
{{< /code >}}
This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`:
{{< output file="content/posts/post-from-custom-archetype.md" >}}
+++
categories = ""
date = 2017-02-13T17:24:43-08:00
description = ""
tags = ""
title = "post from custom archetype"
+++
{{< /output >}}
### Hugo Docs Custom Archetype
As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs:
{{< code file="archetypes/functions.md" >}}
{{< readfile file="/archetypes/functions.md" >}}
{{< /code >}}
{{% note %}}
The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/).
{{% /note %}}
[archetypes directory]: /getting-started/directory-structure/
[`now()`]: http://golang.org/pkg/time/#Now
[configuration file]: /getting-started/configuration/
[sections]: /content-management/sections/
[content types]: /content-management/types/
[front matter]: /content-management/front-matter/
[RFC 3339 format]: https://www.ietf.org/rfc/rfc3339.txt
[taxonomies]: /content-management/taxonomies/
[lookup]: /templates/lookup/
[templates]: /templates/
[front matter]: /content-management/front-matter/
layouts/shortcodes/code.html
+7 -2
View File
@@ -1,5 +1,10 @@
{{ $file := .Get "file" }}
{{ $isHTML := strings.HasSuffix $file "html" }}
{{ $.Scratch.Set "codeLang" "" }}
{{ $suffix := findRE "(\\.[^.]+)$" $file 1 }}
{{ with $suffix }}
{{ $.Scratch.Set "codeLang" (index . 0 | strings.TrimPrefix ".") }}
{{ end }}
{{ with .Get "codeLang" }}{{ $.Scratch.Set "codeLang" . }}{{ end }}
<div class="code relative" id="{{ $file | urlize}}">
{{- with $file -}}
<div class="filename san-serif f6 dib lh-solid pl2 pv2">{{.}}</div>
@@ -11,7 +16,7 @@
{{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}}
{{end}}
<div class="code-copy-content nt3" {{with .Get "download"}}id="{{.}}"{{end}}>
{{ if .Get "nocode" }}{{ .Inner }}{{ else }}{{ if $isHTML }}{{- highlight .Inner "html" "" | -}}{{ else }}<pre><code>{{- .Inner | string -}}</code></pre>{{ end }}{{ end }}
{{ if .Get "nocode" }}{{ $.Inner }}{{ else }}{{ with $.Scratch.Get "codeLang" }}{{- highlight $.Inner . "" | -}}{{ else }}<pre><code>{{- .Inner | string -}}</code></pre>{{ end }}{{ end }}
</div>
</div>