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
- The title of the page. This will appear at the top of the page.
- draft (optional)
- Set draft to
trueif 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.
- 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)
productis 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.
productparameter 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 add
product = ["inspec", "automate"]to the page front matter.
- robots (optional)
- Use robots to add a value to the
robotsmeta tag in a page.
- st_robots (optional)
- Add a
robotsmeta tag specifically for the Swiftype Site Search Crawler.
- The menu that a page belongs in. For example,
menu.serveradds a page to the Infra Server menu.
- Possible menus are:
main(for the top utility bar menu at the top of the docs site)
- The menu title of the page as it would appear in the left navigation menu.
- 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 is
Page Front Matter, so the full page identifier is
overview/style/Page Front Matter.
- 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
- weight (optional)
- The rank that the page will appear in the menu, incremented by 10. Higher numbers are lower in the menu. If
weightexcluded, the page is sorted in the menu alphabetically by page title.
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.