Page Front Matter
This document describes how to format the front matter at the top of each page.
See Hugo’s documentation about front matter for additional information.
Each page starts with TOML front matter which contains metadata about the page and places it properly in the left navigation menu. Below is the TOML front matter for this page which you can use as a reference. Contact the Docs Team if you have any questions about formatting TOML front matter.
Front matter example
The following is a page front matter example. See the following sections for a description of each parameter.
+++
title = "Example Documentation Page"
draft = false
gh_repo = "chef-web-docs"
product = ["client", "server"]
aliases = "/style_guide.html"
robots = ""
st_robots = ""
[menu]
[menu.infra]
title = "Example Page"
identifier = "infra/Example Documentation Page"
parent = "infra"
weight = 40
+++
Front matter parameters
- title
- The title of the page. This will appear at the top of the page.
- draft (optional)
- Set draft to
true
if you do not want Hugo to build the page. - aliases (optional)
- Add an alias if you want Hugo to automatically redirect the user from another page to the page you are writing. Use this if you are renaming or deleting a page.
- gh_repo
- The GitHub repository that the document originates from. This is used to generate “Edit on GitHub” links on each page. For example:
gh_repo = "chef-server"
. - product (optional)
product
is a list of Chef products that are relevant to a page. This list is used to facet search results by product in the documentation site search.This value is automatically added to every page in a section of documentation using Hugo’s Front Matter Cascade to specify the product in the index page of that section.
Use the
product
parameter in a page to override the automatically generated value. You may want to add a product parameter to a page’s front matter if that page references more than one Chef product. For example, if a page in the Chef InSpec documentation describes passing data to Chef Automate, you may want to addproduct = ["inspec", "automate"]
to the page front matter.Relevant values:
automate
desktop
client
server
habitat
inspec
supermarket
workstation
- robots (optional)
- Use robots to add a value to the
robots
meta tag in a page. - st_robots (optional)
- Add a
robots
meta tag specifically for the Swiftype Site Search Crawler.
Menu parameters
- menu
- The menu that a page belongs in. For example,
menu.server
adds a page to the Infra Server menu. - Possible menus are:
main
(for the top utility bar menu at the top of the docs site)overview
automate
desktop
server
infra
inspec
workstation
effortless
supermarket
release_notes
legacy
extra
- title
- The menu title of the page as it would appear in the left navigation menu.
- identifier
- The menu identifier of the page that you are writing. Each identifier must be unique.
The convention we have adopted is to use the identifier of the page’s parent, a forward slash, then the page file, a space, and then the page title.
For example, this page’s parent identifier is
overview/style
, the menu title isPage Front Matter
, so the full page identifier isoverview/style/Page Front Matter
. - parent
- The page’s parent menu identifier.
The convention we have adopted is to append the different menu levels together, separated by a forward slash, and starting with the highest level. For example, this page is nested under Overview and then style, so the page’s parent identifier is
overview/style
. - weight (optional)
- The rank that the page will appear in the menu, incremented by 10. Higher numbers are lower in the menu. If
weight
excluded, the page is sorted in the menu alphabetically by page title.
Menu titles
Keep menu titles short and succinct. These will often be shorter than the page title because readers can glean the context of a page from its location in a menu.