Front matter
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.
Front matter formats
Hugo supports four formats for front matter, each with their own identifying tokens.
- TOML
- identified by opening and closing
+++
. - YAML
- identified by opening and closing
---
. - JSON
- a single JSON object surrounded by ‘
{
’ and ‘}
’, followed by a new line. - ORG
- a group of Org mode keywords in the format ‘
#+KEY: VALUE
’. Any line that does not start with#+
ends the front matter section. Keyword values can be either strings (#+KEY: VALUE
) or a whitespace separated list of strings (#+KEY[]: VALUE_1 VALUE_2
).
Example
categories:
- Development
- VIM
date: "2012-04-06"
description: spf13-vim is a cross platform distribution of vim plugins and resources
for Vim.
slug: spf13-vim-3-0-release-and-new-website
tags:
- .vimrc
- plugins
- spf13-vim
- vim
title: spf13-vim 3.0 release and new website
categories = ['Development', 'VIM']
date = '2012-04-06'
description = 'spf13-vim is a cross platform distribution of vim plugins and resources for Vim.'
slug = 'spf13-vim-3-0-release-and-new-website'
tags = ['.vimrc', 'plugins', 'spf13-vim', 'vim']
title = 'spf13-vim 3.0 release and new website'
{
"categories": [
"Development",
"VIM"
],
"date": "2012-04-06",
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
"slug": "spf13-vim-3-0-release-and-new-website",
"tags": [
".vimrc",
"plugins",
"spf13-vim",
"vim"
],
"title": "spf13-vim 3.0 release and new website"
}
Front matter variables
Predefined
There are a few predefined variables that Hugo is aware of. See Page Variables for how to call many of these predefined variables in your templates.
- aliases
- 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 for details.
- audio
- An array of paths to audio files related to the page; used by the
opengraph
internal template to populateog:audio
. - cascade
- 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 for details.
- date
- The datetime assigned to this page. This is usually fetched from the
date
field in front matter, but this behavior is configurable. - description
- The description for the content.
- draft
- If
true
, the content will not be rendered unless the--buildDrafts
flag is passed to thehugo
command. - expiryDate
- 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 thehugo
command. - headless
- If
true
, sets a leaf bundle to be headless. - images
- An array of paths to images related to the page; used by internal templates such as
_internal/twitter_cards.html
. - isCJKLanguage
- If
true
, Hugo will explicitly treat the content as a CJK language; both.Summary
and.WordCount
work properly in CJK languages. - keywords
- The meta keywords for the content.
- layout
- The layout Hugo should select from the lookup order 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. - lastmod
- The datetime at which the content was last modified.
- linkTitle
- Used for creating links to content; if set, Hugo defaults to using the
linkTitle
before thetitle
. Hugo can also order lists of content bylinkTitle
. - markup
- experimental; specify
"rst"
for reStructuredText (requiresrst2html
) or"md"
(default) for Markdown. - outputs
- Allows you to specify output formats specific to the content. See output formats.
- publishDate
- If in the future, content will not be rendered unless the
--buildFuture
flag is passed tohugo
. - resources
- Used for configuring page bundle resources. See Page Resources.
- series
- An array of series this page belongs to, as a subset of the
series
taxonomy; used by theopengraph
internal template to populateog:see_also
. - slug
- Overrides the last segment of the URL path. Not applicable to section pages. See URL Management for details.
- summary
- Text used when providing a summary of the article in the
.Summary
page variable; details available in the content-summaries section. - title
- The title for the content.
- type
- The type of the content; this value will be automatically derived from the directory (i.e., the section) if not specified in front matter.
- url
- Overrides the entire URL path. Applicable to regular pages and section pages. See URL Management for details.
- videos
- An array of paths to videos related to the page; used by the
opengraph
internal template to populateog:video
. - weight
- used for ordering your content in lists. 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.
- <taxonomies>
- Field name of the plural form of the index. See
tags
andcategories
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.
User-defined
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.
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.
include_toc: true
show_comments: false
include_toc = true
show_comments = false
{
"include_toc": true,
"show_comments": false
}
Front matter cascade
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.
Target specific pages
The cascade
block can be a slice with a optional _target
keyword, allowing for multiple cascade
values targeting different page sets.
cascade:
- _target:
kind: page
lang: en
path: /blog/**
background: yosemite.jpg
- _target:
kind: section
background: goldenbridge.jpg
title: Blog
title = 'Blog'
[[cascade]]
background = 'yosemite.jpg'
[cascade._target]
kind = 'page'
lang = 'en'
path = '/blog/**'
[[cascade]]
background = 'goldenbridge.jpg'
[cascade._target]
kind = 'section'
{
"cascade": [
{
"_target": {
"kind": "page",
"lang": "en",
"path": "/blog/**"
},
"background": "yosemite.jpg"
},
{
"_target": {
"kind": "section"
},
"background": "goldenbridge.jpg"
}
],
"title": "Blog"
}
Keywords available for _target
:
- path
- A 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 supports double-asterisks so you can match for patterns like
/blog/*/**
to match anything from the third level and down. - kind
- A Glob pattern matching the Page’s Kind(s), e.g. “{home,section}”.
- lang
- A Glob pattern matching the Page’s language, e.g. “{en,sv}”.
- environment
- A Glob pattern matching the build environment, e.g. “{production,development}”
Any of the above can be omitted.
Example
In content/blog/_index.md
cascade:
banner: images/typewriter.jpg
title: Blog
title = 'Blog'
[cascade]
banner = 'images/typewriter.jpg'
{
"cascade": {
"banner": "images/typewriter.jpg"
},
"title": "Blog"
}
With the above example the Blog section page and its descendants will return images/typewriter.jpg
when .Params.banner
is invoked unless:
- Said descendant has its own
banner
value set - Or a closer ancestor node has its own
cascade.banner
value set.
Order content through front matter
You can assign content-specific weight
in the front matter of your content. These values are especially useful for ordering in list views. You can use weight
for ordering of content and the convention of <TAXONOMY>_weight
for ordering content within a taxonomy. See Ordering and Grouping Hugo Lists to see how weight
can be used to organize your content in list views.
Override global markdown configuration
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.