mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
ba45da9d03
32356e4e Fix typo in header of shortcode-templates.md c8f1a2d2 Correct code example for index template function bfa6a55d Escape code fencing ff8b2f99 Fix typos in deployment with wercker tutorial 557c36e8 theme: Merge commit '7fbb4bed25001182bfeb91f79db0f0c1936582ee' 7fbb4bed Squashed 'themes/gohugoioTheme/' changes from 7dd8a302..ca53082d ce31cee0 Add "See Also" config 158cee1b Make the tags into keywords 61600be6 Add a note to the related section 49edb5a2 Relase 0.27.1 c9bbc001 releaser: Add release notes to /docs for release of 0.27.1 213c6c3b Add bugs poster 8b4590cd Add KeyCDN integration tutorial 2b277859 Add tutorial videos to several docs pages 950fef1f Update roadmap to link to the correct milestones page 496f5bf6 Rename relnotes d6f9378d Bump Netlify versions to 0.27 087fde7f Update 0.27 release notes 603f94ae docs: Document Related Content 3790f6a3 releaser: Bump versions for release of 0.27 0948868c releaser: Add release notes to /docs for release of 0.27 git-subtree-dir: docs git-subtree-split: 32356e4eabe357ae914f4d1d59e8ae31ce936723
200 lines
8.1 KiB
Markdown
200 lines
8.1 KiB
Markdown
---
|
|
title: Front Matter
|
|
linktitle:
|
|
description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
|
|
date: 2017-01-09
|
|
publishdate: 2017-01-09
|
|
lastmod: 2017-02-24
|
|
categories: [content management]
|
|
keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
|
|
menu:
|
|
docs:
|
|
parent: "content-management"
|
|
weight: 30
|
|
weight: 30 #rem
|
|
draft: false
|
|
aliases: [/content/front-matter/]
|
|
toc: 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][pagevars] 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][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][lookup] 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"][definetype]
|
|
|
|
`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`][bylinktitle].
|
|
|
|
`markup`
|
|
: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
|
|
|
|
`outputs`
|
|
: allows you to specify output formats specific to the content. See [output formats][outputs].
|
|
|
|
`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][ordering].
|
|
|
|
{{% note "Hugo's Default URL Destinations" %}}
|
|
If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) 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
|
|
```
|
|
|
|
These two user-defined fields can then be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][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][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][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][config].
|
|
|
|
## Front Matter Format Specs
|
|
|
|
* [TOML Spec][toml]
|
|
* [YAML Spec][yaml]
|
|
* [JSON Spec][json]
|
|
|
|
[variables]: /variables/
|
|
[aliases]: /content-management/urls/#aliases/
|
|
[archetype]: /content-management/archetypes/
|
|
[bylinktitle]: /templates/lists/#by-link-title
|
|
[config]: /getting-started/configuration/ "Hugo documentation for site configuration"
|
|
[content type]: /content-management/types/
|
|
[contentorg]: /content-management/organization/
|
|
[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter"
|
|
[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
|
|
[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter."
|
|
[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
|
|
[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
|
|
[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
|
|
[pagevars]: /variables/page/
|
|
[section]: /content-management/sections/
|
|
[taxweight]: /content-management/taxonomies/
|
|
[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
|
|
[urls]: /content-management/urls/
|
|
[variables]: /variables/
|
|
[yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"
|