HUGO

  • News
  • Docs
  • Themes
  • Community
  • GitHub
Star

What's on this Page

    • Front Matter Formats
      • TOML Example
      • YAML Example
      • JSON Example
    • Front Matter Variables
      • Predefined
      • User-Defined
    • Order Content Through Front Matter
    • Override Global Markdown Configuration
    • Front Matter Format Specs
CONTENT MANAGEMENT

Front Matter

Hugo allows you to add front matter in yaml, toml, or json to your content files.

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

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.

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

These two user-defined fields can then 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.

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

  • TOML Spec
  • YAML Spec
  • JSON Spec

See Also

  • Data Templates
  • Archetypes
  • Configure Hugo
  • Taxonomy Templates
  • Taxonomies
  • About Hugo
    • Overview
    • Hugo Features
    • The Benefits of Static
    • Roadmap
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • Themes
    • Themes Overview
    • Install and Use Themes
    • Customize a Theme
    • Create a Theme
  • Content Management
    • Content Management Overview
    • Organization
    • Supported Content Formats
    • Front Matter
    • Shortcodes
    • Related Content
    • Sections
    • Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .Param
    • .Scratch
    • .Unix
    • Math
    • absLangURL
    • absURL
    • after
    • apply
    • base64
    • chomp
    • countrunes
    • countwords
    • dateFormat
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • findRE
    • first
    • ge
    • getenv
    • gt
    • hasPrefix
    • highlight
    • htmlEscape
    • htmlUnescape
    • humanize
    • i18n
    • imageConfig
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang.NumFmt
    • last
    • le
    • lower
    • lt
    • markdownify
    • md5
    • ne
    • now
    • partialCached
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • relLangURL
    • relURL
    • relref
    • render
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • time
    • title
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • CLI
  • Troubleshooting
    • Troubleshoot
    • Accented Characters in URLs
    • Build Performance
    • EOF Error
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Host-Agnostic Deploys with Nanobox
    • Host on Netlify
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on Bitbucket
    • Deployment with Wercker
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
“Front Matter” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page
By the Hugo Authors

The Hugo logos are copyright © Steve Francia 2013–2017.

The Hugo Gopher is based on an original work by Renée French.

  • File an Issue
  • Get Help
  • Discuss the Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays
  • News
  • Docs
  • Themes
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Themes
  • Content Management
  • Templates
  • Functions
  • Variables
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute