mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
a6e635ca7d
fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
430 lines
15 KiB
Markdown
430 lines
15 KiB
Markdown
---
|
||
title: Front matter
|
||
description: Use front matter to add metadata to your content.
|
||
categories: [content management]
|
||
keywords: [front matter,yaml,toml,json,metadata,archetypes]
|
||
menu:
|
||
docs:
|
||
parent: content-management
|
||
weight: 60
|
||
weight: 60
|
||
toc: true
|
||
aliases: [/content/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.
|
||
|
||
[json]: https://www.json.org/
|
||
[toml]: https://toml.io/
|
||
[yaml]: https://yaml.org/
|
||
|
||
See examples of front matter delimiters by toggling between the serialization formats below.
|
||
|
||
{{< code-toggle file=content/example.md fm=true >}}
|
||
title = 'Example'
|
||
date = 2024-02-02T04:14:54-08:00
|
||
draft = false
|
||
weight = 10
|
||
[params]
|
||
author = 'John Smith'
|
||
{{< /code-toggle >}}
|
||
|
||
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.
|
||
|
||
[scalar]: /getting-started/glossary/#scalar
|
||
[arrays]: /getting-started/glossary/#array
|
||
[maps]: /getting-started/glossary/#map
|
||
[boolean]: /getting-started/glossary/#boolean
|
||
[integer]: /getting-started/glossary/#integer
|
||
[float]: /getting-started/glossary/#float
|
||
[string]: /getting-started/glossary/#string
|
||
|
||
## Fields
|
||
|
||
The most common front matter fields are `date`, `draft`, `title`, and `weight`, but you can specify metadata using any of fields below.
|
||
|
||
{{% note %}}
|
||
The field names below are reserved. For example, you cannot create a custom field named `type`. Create custom fields under the `params` key. See the [parameters] section for details.
|
||
|
||
[parameters]: #parameters
|
||
{{% /note %}}
|
||
|
||
###### 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.
|
||
|
||
[`aliases`]: /methods/page/aliases/
|
||
[aliases]: /content-management/urls/#aliases
|
||
|
||
###### build
|
||
|
||
(`map`) A map of [build options].
|
||
|
||
[build options]: /content-management/build-options/
|
||
|
||
###### cascade {#cascade-field}
|
||
|
||
(`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.
|
||
|
||
[cascade]: #cascade
|
||
|
||
###### 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.
|
||
|
||
[`date`]: /methods/page/date/
|
||
|
||
###### 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.
|
||
|
||
[`description`]: /methods/page/description/
|
||
|
||
###### 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.
|
||
|
||
[`draft`]: /methods/page/draft/
|
||
|
||
###### 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.
|
||
|
||
[`expirydate`]: /methods/page/expirydate/
|
||
|
||
###### 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].
|
||
|
||
[leaf bundles]: /content-management/page-bundles/#leaf-bundles
|
||
[page resources]: /content-management/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.
|
||
|
||
[`fuzzywordcount`]: /methods/page/wordcount/
|
||
[`readingtime`]: /methods/page/readingtime/
|
||
[`summary`]: /methods/page/summary/
|
||
[`wordcount`]: /methods/page/wordcount/
|
||
[cjk]: /getting-started/glossary/#cjk
|
||
|
||
###### 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.
|
||
|
||
[`keywords`]: /methods/page/keywords/
|
||
[taxonomy]: /getting-started/glossary/#taxonomy
|
||
|
||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||
<!--
|
||
kind
|
||
: The kind of page, e.g. "page", "section", "home" etc. This is usually derived from the content path.
|
||
-->
|
||
|
||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||
<!--
|
||
lang
|
||
: The language code for this page. This is usually derived from the module mount or filename.
|
||
-->
|
||
|
||
###### 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.
|
||
|
||
[`lastmod`]: /methods/page/date/
|
||
|
||
###### 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.
|
||
|
||
[`layout`]: /methods/page/layout/
|
||
[template lookup order]: /templates/lookup-order/
|
||
[target a specific template]: templates/lookup-order/#target-a-template
|
||
|
||
###### linkTitle
|
||
|
||
(`string`) Typically a shorter version of the `title`. Access this value from a template using the [`LinkTitle`] method on a `Page` object.
|
||
|
||
[`linktitle`]: /methods/page/linktitle/
|
||
|
||
###### 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.
|
||
|
||
[content formats]: /content-management/formats/#classification
|
||
|
||
###### menus
|
||
|
||
(`string`,`string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
|
||
|
||
[menus]: /content-management/menus/#define-in-front-matter
|
||
|
||
###### outputs
|
||
|
||
(`string array`) The [output formats] to render.
|
||
|
||
[output formats]: /templates/output-formats/
|
||
|
||
<!-- Added in v0.123.0 but purposefully omitted from documentation. -->
|
||
<!--
|
||
path
|
||
: The canonical page path.
|
||
-->
|
||
|
||
###### params
|
||
|
||
{{< new-in 0.123.0 >}}
|
||
|
||
(`map`) A map of custom [page parameters].
|
||
|
||
[page parameters]: #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.
|
||
|
||
[`publishdate`]: /methods/page/publishdate/
|
||
|
||
###### resources
|
||
|
||
(`map array`) An array of maps to provide metadata for [page resources].
|
||
|
||
[page-resources]: /content-management/page-resources/#page-resources-metadata
|
||
|
||
###### 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.
|
||
|
||
[sitemap templates]: /templates/sitemap/
|
||
[`sitemap`]: /methods/page/sitemap/
|
||
|
||
###### 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.
|
||
|
||
[`slug`]: /methods/page/slug/
|
||
[URL management]: /content-management/urls/#slug
|
||
|
||
###### 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.
|
||
|
||
[`Summary`]: /methods/page/summary/
|
||
|
||
###### title
|
||
|
||
(`string`) The page title. Access this value from a template using the [`Title`] method on a `Page` object.
|
||
|
||
[`title`]: /methods/page/title/
|
||
|
||
###### 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.
|
||
|
||
[`translationkey`]: /methods/page/translationkey/
|
||
|
||
###### 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.
|
||
|
||
[content type]: /getting-started/glossary/#content-type
|
||
[`type`]: /methods/page/type/
|
||
|
||
###### 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.
|
||
|
||
[page collection]: /getting-started/glossary/#page-collection
|
||
[weight]: /getting-started/glossary/#weight
|
||
[`weight`]: /methods/page/weight/
|
||
|
||
## Parameters
|
||
|
||
{{< new-in 0.123.0 >}}
|
||
|
||
Specify custom page parameters under the `params` key in front matter:
|
||
|
||
{{< code-toggle file=content/example.md fm=true >}}
|
||
title = 'Example'
|
||
date = 2024-02-02T04:14:54-08:00
|
||
draft = false
|
||
weight = 10
|
||
[params]
|
||
author = 'John Smith'
|
||
{{< /code-toggle >}}
|
||
|
||
Access these values from a template using the [`Params`] or [`Param`] method on a `Page` object.
|
||
|
||
[`param`]: /methods/page/param/
|
||
[`params`]: /methods/page/params/
|
||
|
||
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.
|
||
|
||
[`opengraph.html`]: {{% eturl opengraph %}}
|
||
[`schema.html`]: {{% eturl schema %}}
|
||
[`twitter_cards.html`]: {{% eturl twitter_cards %}}
|
||
[embedded templates]: /templates/embedded/
|
||
|
||
## Taxonomies
|
||
|
||
Classify content by adding taxonomy terms to front matter. For example, with this site configuration:
|
||
|
||
{{< code-toggle file=hugo >}}
|
||
[taxonomies]
|
||
tag = 'tags'
|
||
genre = 'genres'
|
||
{{< /code-toggle >}}
|
||
|
||
Add taxonomy terms as shown below:
|
||
|
||
{{< code-toggle file=content/example.md fm=true >}}
|
||
title = 'Example'
|
||
date = 2024-02-02T04:14:54-08:00
|
||
draft = false
|
||
weight = 10
|
||
tags = ['red','blue']
|
||
genres = ['mystery','romance']
|
||
[params]
|
||
author = 'John Smith'
|
||
{{< /code-toggle >}}
|
||
|
||
You can add taxonomy terms to the front matter of any these [page kinds]:
|
||
|
||
- `home`
|
||
- `page`
|
||
- `section`
|
||
- `taxonomy`
|
||
- `term`
|
||
|
||
[page kinds]: /getting-started/glossary/#page-kind
|
||
|
||
Access taxonomy terms from a template using the [`Params`] or [`GetTerms`] method on a `Page` object. For example:
|
||
|
||
{{< code file=layouts/_default/single.html >}}
|
||
{{ with .GetTerms "tags" }}
|
||
<p>Tags</p>
|
||
<ul>
|
||
{{ range . }}
|
||
<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
|
||
{{ end }}
|
||
</ul>
|
||
{{ end }}
|
||
{{< /code >}}
|
||
|
||
[`Params`]: /methods/page/params/
|
||
[`GetTerms`]: /methods/page/getterms/
|
||
|
||
## Cascade
|
||
|
||
Any [node] can pass down to its descendants a set of front matter values.
|
||
|
||
[node]: /getting-started/glossary/#node
|
||
|
||
### 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.
|
||
|
||
{{< code-toggle file=content/_index.md fm=true >}}
|
||
title ="Home"
|
||
[[cascade]]
|
||
[cascade.params]
|
||
background = "yosemite.jpg"
|
||
[cascade._target]
|
||
path="/articles/**"
|
||
lang="en"
|
||
kind="page"
|
||
[[cascade]]
|
||
[cascade.params]
|
||
background = "goldenbridge.jpg"
|
||
[cascade._target]
|
||
kind="section"
|
||
{{</ code-toggle >}}
|
||
|
||
Use any combination of these keywords to target a set of pages:
|
||
|
||
###### path {#cascade-path}
|
||
|
||
(`string`) 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 supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
|
||
|
||
###### kind {#cascade-kind}
|
||
|
||
(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
|
||
|
||
###### lang {#cascade-lang}
|
||
|
||
(`string`) A Glob pattern matching the Page's language, e.g. "{en,sv}".
|
||
|
||
###### environment {#cascade-environment}
|
||
|
||
(`string`) A Glob pattern matching the build environment, e.g. "{production,development}"
|
||
|
||
Any of the above can be omitted.
|
||
|
||
{{% note %}}
|
||
With a multilingual site it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section, taxonomy, or term page for each language.
|
||
|
||
With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a section, taxonomy, or term page for each language; the `lang` keyword is ignored.
|
||
{{% /note %}}
|
||
|
||
### Example
|
||
|
||
{{< code-toggle file=content/posts/_index.md fm=true >}}
|
||
date = 2024-02-01T21:25:36-08:00
|
||
title = 'Posts'
|
||
[cascade]
|
||
[cascade.params]
|
||
banner = 'images/typewriter.jpg'
|
||
{{</ code-toggle >}}
|
||
|
||
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:
|
||
|
||
{{< code file=content/example.org lang=text >}}
|
||
#+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
|
||
{{< /code >}}
|
||
|
||
Note that you can also specify array elements on a single line:
|
||
|
||
{{< code file=content/example.org lang=text >}}
|
||
#+TAGS[]: red blue
|
||
{{< /code >}}
|
||
|
||
[content format]: /content-management/formats/
|
||
[emacs org mode]: https://orgmode.org/
|