github.com/shohhei1126/hugo@v0.42.2-0.20180623210752-3d5928889ad7/docs/content/en/content-management/front-matter.md (about)

     1  ---
     2  title: Front Matter
     3  linktitle:
     4  description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
     5  date: 2017-01-09
     6  publishdate: 2017-01-09
     7  lastmod: 2017-02-24
     8  categories: [content management]
     9  keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"]
    10  menu:
    11    docs:
    12      parent: "content-management"
    13      weight: 30
    14  weight: 30	#rem
    15  draft: false
    16  aliases: [/content/front-matter/]
    17  toc: true
    18  ---
    19  
    20  **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.
    21  
    22  {{< youtube Yh2xKRJGff4 >}}
    23  
    24  ## Front Matter Formats
    25  
    26  Hugo supports three formats for front matter, each with their own identifying tokens.
    27  
    28  TOML
    29  : identified by opening and closing `+++`.
    30  
    31  YAML
    32  : identified by opening and closing `---`.
    33  
    34  JSON
    35  : a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
    36  
    37  ### Example
    38  
    39  {{< code-toggle >}}
    40  +++
    41  title = "spf13-vim 3.0 release and new website"
    42  description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
    43  tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
    44  date = "2012-04-06"
    45  categories = [
    46    "Development",
    47    "VIM"
    48  ]
    49  slug = "spf13-vim-3-0-release-and-new-website"
    50  +++
    51  {{</ code-toggle >}}
    52  
    53  ## Front Matter Variables
    54  
    55  ### Predefined
    56  
    57  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.
    58  
    59  aliases
    60  : 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.
    61  
    62  date
    63  : the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in [archetype][].
    64  
    65  description
    66  : the description for the content.
    67  
    68  draft
    69  : if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
    70  
    71  expiryDate
    72  : 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.
    73  
    74  headless
    75  : if `true`, sets a leaf bundle to be [headless][headless-bundle].
    76  
    77  isCJKLanguage
    78  : if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
    79  
    80  keywords
    81  : the meta keywords for the content.
    82  
    83  layout
    84  : 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]
    85  
    86  lastmod
    87  : the datetime at which the content was last modified.
    88  
    89  linkTitle
    90  : 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].
    91  
    92  markup
    93  : **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
    94  
    95  outputs
    96  : allows you to specify output formats specific to the content. See [output formats][outputs].
    97  
    98  publishDate
    99  : if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
   100  
   101  resources
   102  : used for configuring page bundle resources. See [Page Resources][page-resources].
   103  
   104  slug
   105  : 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.
   106  
   107  title
   108  : the title for the content.
   109  
   110  type
   111  : the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter.
   112  
   113  url
   114  : 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
   115  the multilingual feature.
   116  
   117  weight
   118  : used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first.
   119  
   120  \<taxonomies\>
   121  : 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._
   122  
   123  {{% note "Hugo's Default URL Destinations" %}}
   124  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.
   125  {{% /note %}}
   126  
   127  ### User-Defined
   128  
   129  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.
   130  
   131  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.
   132  
   133  {{< code-toggle copy="false" >}}
   134  include_toc: true
   135  show_comments: false
   136  {{</ code-toggle >}}
   137  
   138  
   139  ## Order Content Through Front Matter
   140  
   141  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.
   142  
   143  ## Override Global Markdown Configuration
   144  
   145  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].
   146  
   147  ## Front Matter Format Specs
   148  
   149  * [TOML Spec][toml]
   150  * [YAML Spec][yaml]
   151  * [JSON Spec][json]
   152  
   153  [variables]: /variables/
   154  [aliases]: /content-management/urls/#aliases/
   155  [archetype]: /content-management/archetypes/
   156  [bylinktitle]: /templates/lists/#by-link-title
   157  [config]: /getting-started/configuration/ "Hugo documentation for site configuration"
   158  [content type]: /content-management/types/
   159  [contentorg]: /content-management/organization/
   160  [definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter"
   161  [headless-bundle]: /content-management/page-bundles/#headless-bundle
   162  [json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation"
   163  [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."
   164  [lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating."
   165  [ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates"
   166  [outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating"
   167  [page-resources]: /content-management/page-resources/
   168  [pagevars]: /variables/page/
   169  [section]: /content-management/sections/
   170  [taxweight]: /content-management/taxonomies/
   171  [toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language"
   172  [urls]: /content-management/urls/
   173  [variables]: /variables/
   174  [yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language"