shithub: hugo

--- a/docs/content/content/archetypes.md

+++ b/docs/content/content/archetypes.md

@@ -1,5 +1,5 @@

---

-lastmod: 2015-12-23

+lastmod: 2016-10-01

 date: 2014-05-14T02:13:50Z

 menu:

   main:

@@ -11,22 +11,28 @@

 toc: true

---

-Hugo v0.11 introduced the concept of a content builder. Using the

-command: <code>hugo new <em>[relative new content path]</em></code>,

-you can start a content file with the date and title automatically set.

-While this is a welcome feature, active writers need more.

+In Hugo v0.11, we introduced the concept of a content builder. Using the CLI

+command <code>hugo new <em>[path/to/my/content]</em></code>, an author could

+create an empty content file, with the date and title automatically defined in

+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

-with pre-configured [front matter](/content/front-matter) which will

-populate each new content file whenever you run the `hugo new` command.

+When defining a custom content type, you can use an **archetype** as a way to

+define the default metadata for a new post of that type.

+**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

 ### Step 1. Creating an archetype

-In this example scenario, we have a blog with a single content type (blog post).

-We will use ‘tags’ and ‘categories’ for our taxonomies, so let's create an archetype file with ‘tags’ and ‘categories’ pre-defined, as follows:

+In the following example scenario, suppose we have a blog with a single content

+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

@@ -42,11 +48,12 @@

 ### 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 would create the file with the following contents:

+Hugo will now create the file with the following contents:

 #### content/post/my-new-post.md

@@ -59,13 +66,21 @@

+++

```

-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

-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

@@ -77,11 +92,14 @@

+++

```

-Now let's create a new musician.

+Now, let's create a new musician.

     $ 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

@@ -104,12 +122,11 @@

 (e.g. `config.toml`) using the `MetaDataFormat` directive.

 Possible values are `"toml"`, `"yaml"` and `"json"`.

 ## 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 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.

@@ -126,4 +143,6 @@

 > `title` and `date`, which are dynamic and unique for each piece of content,

 > 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.