hugo/content/en/content-management/front-matter.md
Bjørn Erik Pedersen 41bc6f702a Squashed 'docs/' changes from 2201ac0e5..2c0125b52
2c0125b52 Remove .Site.Author
2cf8841b3 Update partialCached.md (#1924)
385487191 Update data-templates.md (#1926)
ce207e141 Remove redundant markdown and fix a few typos (#1936)
3687c2953 Make heading id linkable, take 2
45c79bea7 Make heading id linkable
b22079344 Delete duplicates the lines 557-569 and 570-582. (#1934)
0a90dc122 Rework the taxonomy variables page (#1935)
7f8979c50 Update theme
26e682a3a Update multilingual.md
d40e7693f Update postcss.md
375d75c01 Update postcss npm instructions (#1931)
63020094a Emphasize Window shell selection (#1930)
56824be2c Update configuration.md
b7b8f16b3 Docu 'Theme components': minor fix (#1929)
09dc81a05 Remove Docker from BSD page (#1927)
205fea204 netlify: Hugo 0.108.0
6abe49c28 Merge commit 'da670c38ee63a7fef25e2b9f42519232055b60dc'
12b59a4c5 docs: Add basic doc for wrapStandAloneImageWithinParagraph etc.
ba07bd970 dartsass: Add sourceMapIncludeSources option

git-subtree-dir: docs
git-subtree-split: 2c0125b5290494d49334606c451446ebd9df3c21
2022-12-20 11:04:41 +01:00

10 KiB

title linkTitle description lastmod categories keywords menu toc weight aliases
Front Matter Front Matter Hugo allows you to add front matter in yaml, toml, or json to your content files. 2017-02-24
content management
front matter
yaml
toml
json
metadata
archetypes
docs
parent weight
content-management 60
true 60
/content/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.

{{< youtube Yh2xKRJGff4 >}}

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

{{< code-toggle >}} title = "spf13-vim 3.0 release and new website" description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] date = "2012-04-06" categories = [ "Development", "VIM" ] slug = "spf13-vim-3-0-release-and-new-website" {{< /code-toggle >}}

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 populate og: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 the hugo 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 the hugo 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 the title. Hugo can also order lists of content by linktitle.
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 to hugo.
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 the opengraph internal template to populate og:see_also.
slug
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.
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
the full path to the content from the web root. It makes no assumptions about the path of the content file. See URL Management.
videos
an array of paths to videos related to the page; used by the opengraph internal template to populate og: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 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.

{{% note "Hugo's Default URL Destinations" %}} If neither slug nor url is present and permalinks are not configured otherwise in your site config file, Hugo will use the filename of your content to create the output URL. See Content Organization for an explanation of paths in Hugo and URL Management for ways to customize Hugo's default behaviors. {{% /note %}}

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.

{{< code-toggle copy="false" >}} include_toc: true show_comments: false {{</ code-toggle >}}

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.

{{< code-toggle copy="false" >}} title ="Blog" cascade background = "yosemite.jpg" [cascade._target] path="/blog/**" lang="en" kind="page" cascade background = "goldenbridge.jpg" [cascade._target] kind="section" {{</ code-toggle >}}

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

{{< code-toggle copy="false" >}} title: Blog cascade: banner: images/typewriter.jpg {{</ code-toggle >}}

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.

Front Matter Format Specs