Front matter
Overview
The front matter at the top of each content file is metadata that:
- Describes the content
- Augments the content
- Establishes relationships with other content
- Controls the published structure of your site
- Determines template selection
Provide front matter using a serialization format, one of JSON, TOML, or YAML. Hugo determines the front matter format by examining the delimiters that separate the front matter from the page content.
See examples of front matter delimiters by toggling between the serialization formats below.
---
date: 2024-02-02T04:14:54-08:00
draft: false
params:
author: John Smith
title: Example
weight: 10
---
+++
date = 2024-02-02T04:14:54-08:00
draft = false
title = 'Example'
weight = 10
[params]
author = 'John Smith'
+++
{
"date": "2024-02-02T04:14:54-08:00",
"draft": false,
"params": {
"author": "John Smith"
},
"title": "Example",
"weight": 10
}
Front matter fields may be scalar, arrays, or maps containing boolean, integer, float, or string values. Note that the TOML format also supports date/time values using unquoted strings.
Fields
The most common front matter fields are date
, draft
, title
, and weight
, but you can specify metadata using any of fields below.
aliases
(string array
) An array of one or more aliases, where each alias is a relative URL that will redirect the browser to the current location. Access these values from a template using the Aliases
method on a Page
object. See the aliases section for details.
build
(map
) A map of build options.
cascade
(map
) 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 the cascade section for details.
date
(string
) The date associated with the page, typically the creation date. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the Date
method on a Page
object.
description
(string
) Conceptually different than the page summary
, the description is typically rendered within a meta
element within the head
element of the published HTML file. Access this value from a template using the Description
method on a Page
object.
draft
(bool
)
If true
, the page will not be rendered unless you pass the --buildDrafts
flag to the hugo
command. Access this value from a template using the Draft
method on a Page
object.
expiryDate
(string
) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the --buildExpired
flag to the hugo
command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the ExpiryDate
method on a Page
object.
headless
(bool
) Applicable to leaf bundles, if true
this value sets the render
and list
build options to never
, creating a headless bundle of page resources.
isCJKLanguage
(bool
) Set to true
if the content language is in the CJK family. This value determines how Hugo calculates word count, and affects the values returned by the WordCount
, FuzzyWordCount
, ReadingTime
, and Summary
methods on a Page
object.
keywords
(string array
) An array of keywords, typically rendered within a meta
element within the head
element of the published HTML file, or used as a taxonomy to classify content. Access these values from a template using the Keywords
method on a Page
object.
lastmod
(string
) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the Lastmod
method on a Page
object.
layout
(string
) Provide a template name to target a specific template, overriding the default template lookup order. Set the value to the base file name of the template, excluding its extension. Access this value from a template using the Layout
method on a Page
object.
linkTitle
(string
) Typically a shorter version of the title
. Access this value from a template using the LinkTitle
method on a Page
object.
markup
(string
) An identifier corresponding to one of the supported content formats. If not provided, Hugo determines the content renderer based on the file extension.
menus
(string
,string array
, or map
) If set, Hugo adds the page to the given menu or menus. See the menus page for details.
outputs
(string array
) The output formats to render.
params
New in v0.123.0(map
) A map of custom page parameters.
publishDate
(string
) The page publication date. Before the publication date, the page will not be rendered unless you pass the --buildFuture
flag to the hugo
command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the PublishDate
method on a Page
object.
resources
(map array
) An array of maps to provide metadata for page resources.
sitemap
(map
) A map of sitemap options. See the sitemap templates page for details. Access these values from a template using the Sitemap
method on a Page
object.
slug
(string
) Overrides the last segment of the URL path. Not applicable to section pages. See the URL management page for details. Access this value from a template using the Slug
method on a Page
object.
summary
(string
) Conceptually different than the page description
, the summary either summarizes the content or serves as a teaser to encourage readers to visit the page. Access this value from a template using the Summary
method on a Page
object.
title
(string
) The page title. Access this value from a template using the Title
method on a Page
object.
translationKey
(string
) An arbitrary value used to relate two or more translations of the same page, useful when the translated pages do not share a common path. Access this value from a template using the TranslationKey
method on a Page
object.
type
(string
) The content type, overriding the value derived from the top level section in which the page resides. Access this value from a template using the Type
method on a Page
object.
url
(string
) Overrides the entire URL path. Applicable to regular pages and section pages. See the URL management page for details.
weight
(int
) The page weight, used to order the page within a page collection. Access this value from a template using the Weight
method on a Page
object.
Parameters
New in v0.123.0Specify custom page parameters under the params
key in front matter:
---
date: 2024-02-02T04:14:54-08:00
draft: false
params:
author: John Smith
title: Example
weight: 10
---
+++
date = 2024-02-02T04:14:54-08:00
draft = false
title = 'Example'
weight = 10
[params]
author = 'John Smith'
+++
{
"date": "2024-02-02T04:14:54-08:00",
"draft": false,
"params": {
"author": "John Smith"
},
"title": "Example",
"weight": 10
}
Access these values from a template using the Params
or Param
method on a Page
object.
Hugo provides embedded templates to optionally insert meta data within the head
element of your rendered pages. These embedded templates expect the following front matter parameters:
Parameter | Data type | Used by these embedded templates |
---|---|---|
audio |
[]string |
opengraph.html |
images |
[]string |
opengraph.html , schema.html , twitter_cards.html |
videos |
[]string |
opengraph.html |
The embedded templates will skip a parameter if not provided in front matter, but will throw an error if the data type is unexpected.
Taxonomies
Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
taxonomies:
genre: genres
tag: tags
[taxonomies]
genre = 'genres'
tag = 'tags'
{
"taxonomies": {
"genre": "genres",
"tag": "tags"
}
}
Add taxonomy terms as shown below:
---
date: 2024-02-02T04:14:54-08:00
draft: false
genres:
- mystery
- romance
params:
author: John Smith
tags:
- red
- blue
title: Example
weight: 10
---
+++
date = 2024-02-02T04:14:54-08:00
draft = false
genres = ['mystery', 'romance']
tags = ['red', 'blue']
title = 'Example'
weight = 10
[params]
author = 'John Smith'
+++
{
"date": "2024-02-02T04:14:54-08:00",
"draft": false,
"genres": [
"mystery",
"romance"
],
"params": {
"author": "John Smith"
},
"tags": [
"red",
"blue"
],
"title": "Example",
"weight": 10
}
You can add taxonomy terms to the front matter of any these page kinds:
home
page
section
taxonomy
term
Access taxonomy terms from a template using the Params
or GetTerms
method on a Page
object. For example:
{{ with .GetTerms "tags" }}
<p>Tags</p>
<ul>
{{ range . }}
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
{{ end }}
</ul>
{{ end }}
Cascade
Any node can pass down to its descendants a set of front matter values.
Target specific pages
The cascade
block can be an array with an optional _target
keyword, allowing you to target different page sets while cascading values.
---
cascade:
- _target:
kind: page
lang: en
path: /articles/**
params:
background: yosemite.jpg
- _target:
kind: section
params:
background: goldenbridge.jpg
title: Home
---
+++
title = 'Home'
[[cascade]]
[cascade._target]
kind = 'page'
lang = 'en'
path = '/articles/**'
[cascade.params]
background = 'yosemite.jpg'
[[cascade]]
[cascade._target]
kind = 'section'
[cascade.params]
background = 'goldenbridge.jpg'
+++
{
"cascade": [
{
"_target": {
"kind": "page",
"lang": "en",
"path": "/articles/**"
},
"params": {
"background": "yosemite.jpg"
}
},
{
"_target": {
"kind": "section"
},
"params": {
"background": "goldenbridge.jpg"
}
}
],
"title": "Home"
}
Use any combination of these keywords to target a set of pages:
path
(string
) 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
(string
) A Glob pattern matching the Page’s Kind(s), e.g. “{home,section}”.
lang
(string
) A Glob pattern matching the Page’s language, e.g. “{en,sv}”.
environment
(string
) A Glob pattern matching the build environment, e.g. “{production,development}”
Any of the above can be omitted.
Example
---
cascade:
params:
banner: images/typewriter.jpg
date: 2024-02-01T21:25:36-08:00
title: Posts
---
+++
date = 2024-02-01T21:25:36-08:00
title = 'Posts'
[cascade]
[cascade.params]
banner = 'images/typewriter.jpg'
+++
{
"cascade": {
"params": {
"banner": "images/typewriter.jpg"
}
},
"date": "2024-02-01T21:25:36-08:00",
"title": "Posts"
}
With the above example the posts 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.
Emacs Org Mode
If your content format is Emacs Org Mode, you may provide front matter using Org Mode keywords. For example:
#+TITLE: Example
#+DATE: 2024-02-02T04:14:54-08:00
#+DRAFT: false
#+AUTHOR: John Smith
#+GENRES: mystery
#+GENRES: romance
#+TAGS: red
#+TAGS: blue
#+WEIGHT: 10
Note that you can also specify array elements on a single line:
#+TAGS[]: red blue