archetypes.md (3092B)
1 ---
2 title: Archetypes
3 linktitle: Archetypes
4 description: Archetypes are templates used when creating new content.
5 date: 2017-02-01
6 publishdate: 2017-02-01
7 keywords: [archetypes,generators,metadata,front matter]
8 categories: ["content management"]
9 menu:
10 docs:
11 parent: "content-management"
12 weight: 70
13 quicklinks:
14 weight: 70 #rem
15 draft: false
16 aliases: [/content/archetypes/]
17 toc: true
18 ---
19
20 ## What are Archetypes?
21
22 **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`.
23
24
25 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.
26
27 {{< code file="archetype-example.sh" >}}
28 hugo new posts/my-first-post.md
29 {{< /code >}}
30
31 The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these:
32
33 1. `archetypes/posts.md`
34 2. `archetypes/default.md`
35 3. `themes/my-theme/archetypes/posts.md`
36 4. `themes/my-theme/archetypes/default.md`
37
38 The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example.
39
40 ## Create a New Archetype Template
41
42 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.
43
44 {{< code file="archetypes/newsletter.md" >}}
45 ---
46 title: "{{ replace .Name "-" " " | title }}"
47 date: {{ .Date }}
48 draft: true
49 ---
50
51 **Insert Lead paragraph here.**
52
53 ## New Cool Posts
54
55 {{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }}
56 * {{ .Title }}
57 {{ end }}
58 {{< /code >}}
59
60 When you create a new newsletter with:
61
62 ```bash
63 hugo new newsletter/the-latest-cool.stuff.md
64 ```
65
66 It will create a new newsletter type of content file based on the archetype template.
67
68 **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.
69
70 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.
71
72
73 ## Directory based archetypes
74
75 Since Hugo `0.49` you can use complete directories as archetype templates. Given this archetype directory:
76
77 ```bash
78 archetypes
79 ├── default.md
80 └── post-bundle
81 ├── bio.md
82 ├── images
83 │ └── featured.jpg
84 └── index.md
85 ```
86
87 ```bash
88 hugo new --kind post-bundle posts/my-post
89 ```
90
91 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.
92
93
94
95 [archetypes directory]: /getting-started/directory-structure/
96 [content types]: /content-management/types/
97 [front matter]: /content-management/front-matter/