front-matter.md (10717B)
1 ---
2 title: Front Matter
3 linktitle:
4 description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
5 date: 2017-01-09
6 publishdate: 2017-01-09
7 lastmod: 2017-02-24
8 categories: [content management]
9 keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
10 menu:
11 docs:
12 parent: "content-management"
13 weight: 30
14 weight: 30 #rem
15 draft: false
16 aliases: [/content/front-matter/]
17 toc: true
18 ---
19
20 **Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
21
22 {{< youtube Yh2xKRJGff4 >}}
23
24 ## Front Matter Formats
25
26 Hugo supports four formats for front matter, each with their own identifying tokens.
27
28 TOML
29 : identified by opening and closing `+++`.
30
31 YAML
32 : identified by opening and closing `---`.
33
34 JSON
35 : a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
36
37 ORG
38 : a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section.
39 Keyword values can be either strings (`#+KEY: VALUE`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`).
40
41 ### Example
42
43 {{< code-toggle >}}
44 title = "spf13-vim 3.0 release and new website"
45 description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
46 tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
47 date = "2012-04-06"
48 categories = [
49 "Development",
50 "VIM"
51 ]
52 slug = "spf13-vim-3-0-release-and-new-website"
53 {{< /code-toggle >}}
54
55 ## Front Matter Variables
56
57 ### Predefined
58
59 There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
60
61 aliases
62 : an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
63
64 audio
65 : an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
66
67 cascade
68 : a map of Front Matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
69
70 date
71 : the datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behaviour is configurable.
72
73 description
74 : the description for the content.
75
76 draft
77 : if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
78
79 expiryDate
80 : the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
81
82 headless
83 : if `true`, sets a leaf bundle to be [headless][headless-bundle].
84
85 images
86 : an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
87
88 isCJKLanguage
89 : if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
90
91 keywords
92 : the meta keywords for the content.
93
94 layout
95 : the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
96
97 lastmod
98 : the datetime at which the content was last modified.
99
100 linkTitle
101 : used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle].
102
103 markup
104 : **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
105
106 outputs
107 : allows you to specify output formats specific to the content. See [output formats][outputs].
108
109 publishDate
110 : if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
111
112 resources
113 : used for configuring page bundle resources. See [Page Resources][page-resources].
114
115 series
116 : an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
117
118 slug
119 : appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
120
121 summary
122 : text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
123
124 title
125 : the title for the content.
126
127 type
128 : the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
129
130 url
131 : the full path to the content from the web root. It makes no assumptions about the path of the content file. See [URL Management](/content-management/urls/#set-url-in-front-matter).
132
133 videos
134 : an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
135
136 weight
137 : used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
138
139 \<taxonomies\>
140 : field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._
141
142 {{% note "Hugo's Default URL Destinations" %}}
143 If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
144 {{% /note %}}
145
146 ### User-Defined
147
148 You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
149
150 The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates.
151
152 {{< code-toggle copy="false" >}}
153 include_toc: true
154 show_comments: false
155 {{</ code-toggle >}}
156
157 ## Front Matter Cascade
158
159 Any node or section can pass down to descendants a set of Front Matter values as long as defined underneath the reserved `cascade` Front Matter key.
160
161 ### Target Specific Pages
162
163 {{< new-in "0.76.0" >}}
164
165 Since Hugo 0.76 the `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
166
167 {{< code-toggle copy="false" >}}
168 title ="Blog"
169 [[cascade]]
170 background = "yosemite.jpg"
171 [cascade._target]
172 path="/blog/**"
173 lang="en"
174 kind="page"
175 [[cascade]]
176 background = "goldenbridge.jpg"
177 [cascade._target]
178 kind="section"
179 {{</ code-toggle >}}
180
181 Keywords available for `_target`:
182
183 path
184 : A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching support double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
185
186 kind
187 : A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
188
189 lang
190 : A Glob pattern matching the Page's language, e.g. "{en,sv}".
191
192 environment
193 : A Glob pattern matching the build environment, e.g. "{production,development}"
194
195 Any of the above can be omitted.
196
197 ### Example
198
199 In `content/blog/_index.md`
200
201 {{< code-toggle copy="false" >}}
202 title: Blog
203 cascade:
204 banner: images/typewriter.jpg
205 {{</ code-toggle >}}
206
207 With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
208
209 - Said descendant has its own `banner` value set
210 - Or a closer ancestor node has its own `cascade.banner` value set.
211
212
213
214 ## Order Content Through Front Matter
215
216 You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
217
218 ## Override Global Markdown Configuration
219
220 It's possible to set some options for Markdown rendering in a content's front matter as an override to the [Rendering options set in your project configuration][config].
221
222 ## Front Matter Format Specs
223
224 * [TOML Spec][toml]
225 * [YAML Spec][yaml]
226 * [JSON Spec][json]
227
228 [variables]: /variables/
229 [aliases]: /content-management/urls/#aliases
230 [archetype]: /content-management/archetypes/
231 [bylinktitle]: /templates/lists/#by-link-title
232 [config]: /getting-started/configuration/ "Hugo documentation for site configuration"
233 [content type]: /content-management/types/
234 [contentorg]: /content-management/organization/
235 [headless-bundle]: /content-management/page-bundles/#headless-bundle
236 [json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
237 [lists]: /templates/lists/#order-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
238 [lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
239 [ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
240 [outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
241 [page-resources]: /content-management/page-resources/
242 [pagevars]: /variables/page/
243 [section]: /content-management/sections/
244 [taxweight]: /content-management/taxonomies/
245 [toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
246 [urls]: /content-management/urls/
247 [variables]: /variables/
248 [yaml]: https://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"