mirror of
https://github.com/gohugoio/hugo.git
synced 2025-03-19 04:14:24 +00:00
doc: Improving language in archetypes doc
This commit is contained in:
parent
0721a9c730
commit
ffbf3dd319
1 changed files with 40 additions and 21 deletions
|
@ -1,5 +1,5 @@
|
||||||
---
|
---
|
||||||
lastmod: 2015-12-23
|
lastmod: 2016-10-01
|
||||||
date: 2014-05-14T02:13:50Z
|
date: 2014-05-14T02:13:50Z
|
||||||
menu:
|
menu:
|
||||||
main:
|
main:
|
||||||
|
@ -11,22 +11,28 @@ weight: 50
|
||||||
toc: true
|
toc: true
|
||||||
---
|
---
|
||||||
|
|
||||||
Hugo v0.11 introduced the concept of a content builder. Using the
|
In Hugo v0.11, we introduced the concept of a content builder. Using the CLI
|
||||||
command: <code>hugo new <em>[relative new content path]</em></code>,
|
command <code>hugo new <em>[path/to/my/content]</em></code>, an author could
|
||||||
you can start a content file with the date and title automatically set.
|
create an empty content file, with the date and title automatically defined in
|
||||||
While this is a welcome feature, active writers need more.
|
the front matter of the post. While this was a welcome feature, active writers
|
||||||
|
need more flexibility.
|
||||||
|
|
||||||
Hugo presents the concept of archetypes, which are archetypal content files
|
When defining a custom content type, you can use an **archetype** as a way to
|
||||||
with pre-configured [front matter](/content/front-matter) which will
|
define the default metadata for a new post of that type.
|
||||||
populate each new content file whenever you run the `hugo new` command.
|
|
||||||
|
|
||||||
|
**Archetypes** are quite literally archetypal content files with pre-configured
|
||||||
|
[front matter](/content/front-matter). An archetype will populate each new
|
||||||
|
content file of a given type with any default metadata you've defined whenever
|
||||||
|
you run the `hugo new` command.
|
||||||
|
|
||||||
## Example
|
## Example
|
||||||
|
|
||||||
### Step 1. Creating an archetype
|
### Step 1. Creating an archetype
|
||||||
|
|
||||||
In this example scenario, we have a blog with a single content type (blog post).
|
In the following example scenario, suppose we have a blog with a single content
|
||||||
We will use ‘tags’ and ‘categories’ for our taxonomies, so let's create an archetype file with ‘tags’ and ‘categories’ pre-defined, as follows:
|
type (blog post). Our imaginary blog will use ‘tags’ and ‘categories’ for its
|
||||||
|
taxonomies, so let's create an archetype file with ‘tags’ and ‘categories’
|
||||||
|
pre-defined:
|
||||||
|
|
||||||
#### archetypes/default.md
|
#### archetypes/default.md
|
||||||
|
|
||||||
|
@ -42,11 +48,12 @@ categories = ["x", "y"]
|
||||||
|
|
||||||
### Step 2. Using the archetype
|
### Step 2. Using the archetype
|
||||||
|
|
||||||
Now, with `archetypes/default.md` in place, let's create a new post in the `post` section with the `hugo new` command:
|
Now, with `archetypes/default.md` in place, let's create a new post in the `post`
|
||||||
|
section with the `hugo new` command:
|
||||||
|
|
||||||
$ hugo new post/my-new-post.md
|
$ hugo new post/my-new-post.md
|
||||||
|
|
||||||
Hugo would create the file with the following contents:
|
Hugo will now create the file with the following contents:
|
||||||
|
|
||||||
#### content/post/my-new-post.md
|
#### content/post/my-new-post.md
|
||||||
|
|
||||||
|
@ -59,13 +66,21 @@ categories = ["x", "y"]
|
||||||
+++
|
+++
|
||||||
```
|
```
|
||||||
|
|
||||||
We see that the `title` and `date` variables have been added, in addition to the `tags` and `categories` variables which were carried over from `archetype/default.md`.
|
We see that the `title` and `date` variables have been added, in addition to the
|
||||||
|
`tags` and `categories` variables which were carried over from `archetype/default.md`.
|
||||||
|
|
||||||
Congratulations! We have successfully created an archetype and used it for our new contents. But wait, what if I want to have different variables for another content type, like musicians? No problem.
|
Congratulations! We have successfully created an archetype and used it to
|
||||||
|
quickly scaffold out a new post. But wait, what if we want to create some content
|
||||||
|
that isn't exactly a blog post, like a profile for a musician? Let's see how
|
||||||
|
using **archetypes** can help us out.
|
||||||
|
|
||||||
### Creating custom archetypes
|
### Creating custom archetypes
|
||||||
|
|
||||||
Earlier you created a new content type by adding a new subfolder to the content directory. In our case its name would be `content/musician`. To use the corresponding archetype you just need to create a file named after the content type called `musician.md` in the `archetypes` directory, similar to the one below.
|
Previously, we had created a new content type by adding a new subfolder to the
|
||||||
|
content directory. In this case, its name would be `content/musician`. To begin
|
||||||
|
using a `musician` archetype for each new `musician` post, we simply need to
|
||||||
|
create a file named after the content type called `musician.md`, and put it in
|
||||||
|
the `archetypes` directory, similar to the one below.
|
||||||
|
|
||||||
#### archetypes/musician.md
|
#### archetypes/musician.md
|
||||||
|
|
||||||
|
@ -77,11 +92,14 @@ genre = ""
|
||||||
+++
|
+++
|
||||||
```
|
```
|
||||||
|
|
||||||
Now let's create a new musician.
|
Now, let's create a new musician.
|
||||||
|
|
||||||
$ hugo new musician/mozart.md
|
$ hugo new musician/mozart.md
|
||||||
|
|
||||||
This time, Hugo recognizes the custom archetype and uses it instead of the default one. So the generated file's frontmatter now includes the variables `name`, `bio` and `genre`.
|
This time, Hugo recognizes our custom `musician` archetype and uses it instead of
|
||||||
|
the default one. Take a look at the new `musician/mozart.md` post. You should see
|
||||||
|
that the generated file's front matter now includes the variables `name`, `bio`,
|
||||||
|
and `genre`.
|
||||||
|
|
||||||
#### content/musician/mozart.md
|
#### content/musician/mozart.md
|
||||||
|
|
||||||
|
@ -104,12 +122,11 @@ You can specify a different default format in your site-wide config file
|
||||||
(e.g. `config.toml`) using the `MetaDataFormat` directive.
|
(e.g. `config.toml`) using the `MetaDataFormat` directive.
|
||||||
Possible values are `"toml"`, `"yaml"` and `"json"`.
|
Possible values are `"toml"`, `"yaml"` and `"json"`.
|
||||||
|
|
||||||
|
|
||||||
## Which archetype is being used
|
## Which archetype is being used
|
||||||
|
|
||||||
The following rules apply:
|
The following rules apply when creating new content:
|
||||||
|
|
||||||
* If an archetype with a filename that matches the content type being created, it will be used.
|
* If an archetype with a filename matching the new post's [content type](/content/type) exists, it will be used.
|
||||||
* If no match is found, `archetypes/default.md` will be used.
|
* If no match is found, `archetypes/default.md` will be used.
|
||||||
* If neither is present and a theme is in use, then within the theme:
|
* If neither is present and a theme is in use, then within the theme:
|
||||||
* If an archetype with a filename that matches the content type being created, it will be used.
|
* If an archetype with a filename that matches the content type being created, it will be used.
|
||||||
|
@ -126,4 +143,6 @@ file name) and the `date` in RFC 3339 format based on
|
||||||
> `title` and `date`, which are dynamic and unique for each piece of content,
|
> `title` and `date`, which are dynamic and unique for each piece of content,
|
||||||
> are the sole exceptions.*
|
> are the sole exceptions.*
|
||||||
|
|
||||||
Content type is automatically detected based on the path. You are welcome to declare which type to create using the `--kind` flag during creation.
|
The content type is automatically detected based on the file path passed to the
|
||||||
|
Hugo CLI command <code>hugo new <em>[my-content-type/post-name]</em></code>. To
|
||||||
|
override the content type for a new post, include the `--kind` flag during creation.
|
||||||
|
|
Loading…
Reference in a new issue