diff --git a/docs/content/content/archetypes.md b/docs/content/content/archetypes.md index 1958da008..ca55bb038 100644 --- 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 @@ weight: 50 toc: true --- -Hugo v0.11 introduced the concept of a content builder. Using the -command: hugo new [relative new content path], -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 hugo new [path/to/my/content], 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 @@ categories = ["x", "y"] ### 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 @@ 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 -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 @@ genre = "" +++ ``` -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 @@ You can specify a different default format in your site-wide config file (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 @@ file name) and the `date` in RFC 3339 format based on > `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 hugo new [my-content-type/post-name]. To +override the content type for a new post, include the `--kind` flag during creation.