hugo/content/content-management/front-matter.md
Bjørn Erik Pedersen 900b5f6cfe Squashed 'docs/' changes from 1dc05a16b..715741f73
715741f73 Add Netlify config for a split testin branch
4917f0636 Mention that math add/sub/mul/div functions can do float math too
31632beeb Document .Site.Params.mainSections
3416ba80d Update sectionvars.md
295ccb463 Update sections.md
15b5a0342 Fix duplicated paragraph
eb13db670 Fix text highlight
fa46cafdf Get 1password-support ready
979bb5698 Add 1password support showcase
ceb94d1e1 Fix readDir function links

git-subtree-dir: docs
git-subtree-split: 715741f7393cec2a9b34254bda6e815e9391a632
2018-02-27 09:36:36 +01:00

8.1 KiB

title linktitle description date publishdate lastmod categories keywords menu weight draft aliases toc
Front Matter Hugo allows you to add front matter in yaml, toml, or json to your content files. 2017-01-09 2017-01-09 2017-02-24
content management
front matter
yaml
toml
json
metadata
archetypes
docs
parent weight
content-management 30
30 false
/content/front-matter/
true

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 three 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.

TOML Example

+++
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"
+++

YAML Example

---
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" ]
lastmod: 2015-12-23
date: "2012-04-06"
categories:
  - "Development"
  - "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---

JSON Example

{
    "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"
}

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.
date
the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in archetype.
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.
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 "Defining a Content Type"
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.
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.
taxonomies
these will use the field name of the plural form of the index; see the tags and categories in the above front matter examples.
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. It also ignores any language prefixes of the multilingual feature.
weight
used for ordering your content in lists.

{{% 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.

include_toc: true
show_comments: false

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 BlackFriday rendering options set in your project configuration.

Front Matter Format Specs