To build the docs locally, from the root of the
chef-web-docs directory, run the command:
Add a New Page
Adding a new page has two steps:
- Create the page
- Add the page to the left navigation bar
From the root of the
chef-web-docs directory, add a completely new page with the command:
hugo new content/page_name.md
Navigate to your new page in the
chef-web-docs/content directory and edit the front matter accordingly.
Add or Remove pages from the Left Nav Bar
Adding, removing, and changing the placement of a page in the left nav involves three steps:
- Defining the page weight in the document’s front matter or the
- Verifying that the page appears as you intend in the left nav
- Adjusting the weighting in affected pages accordingly
Contact the documentation team if you have any questions about adding or removing pages.
Page Front Matter
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.
+++ title = "Example Documentation Page" description = "DESCRIPTION" 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 +++
- The title of the page. This will appear at the top of the page.
- Set draft to
trueif you do not want Hugo to build the page.
- Add an alias if you want Hugo to automatically redirect the user from another page to the page you are writing.
- The GitHub repository that the document originates from. This is used to generate “Edit on GitHub” links on each page. For example:
productis a list of Chef products that are relevant to a page. Relevant values:
This list is used to facet search results in our documentation search by product. Each product section of the documentation has a default product parameter configured using Hugo’s Front Matter Cascade; however, 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.
- Use robots to add a value to the
robotsmeta tag in a page.
- Add a
robotsmeta tag specifically for the Swiftype Site Search Crawler.
- menu title
- The title of the page as it would appear in the left navigation menu.
- menu identifier
- The 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 page file is
style_guide.mdand the page title is
Docs Style Guide, so the full page identifier is
overview/style/style_guide.md Docs Style Guide
- menu parent
- The menu identifier of the page’s parent.
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
- menu weight
- The rank that the page will appear in the menu, incremented by 10. Higher numbers are lower in the menu.