inspec/docs-chef-io/README.md

Chef InSpec Documentation

This is the home of the InSpec Documentation that is deployed on https://docs.chef.io/inspec/ using Hugo modules.

Updating InSpec Docs Content

There are two steps to updating the Chef InSpec documentation on docs.chef.io:

1. Update the documentation in the inspec/inspec repository.
2. Update the InSpec repository module in chef-web-docs.

Documentation Content

Please keep all of the InSpec documentation in the content/inspec directory.

The diagram below shows how documentation content should be organized:

.
├── docs-chef-io
│   ├── archetypes                 # page templates
│   ├── content
│   │   ├── inspec                 # InSpec documentation
│   │   │   ├── resources          # InSpec resource documentation
│   ├── static
│   |   ├── images
│   │   |   ├── inspec             # images
│   ├── layouts
│   |   ├── shortcodes             # reusable text files

To add a new Markdown page, run the following command from the docs-chef-io directory:

hugo new content/inspec/FILENAME.md

This will create a draft page with enough front matter to get you going.

Hugo uses Goldmark which is a superset of Markdown that includes GitHub styled tables, task lists, and definition lists.

See our Style Guide for more information about formatting documentation using Markdown.

Page Front Matter

At the top of each page is a block of front matter that Hugo uses to add a title to each page and locate each page in the left navigation menu in <docs.chef.io>. Below is an example of a page's front matter:

+++
title = "PAGE TITLE"
draft = false
gh_repo = "inspec"

[menu]
  [menu.inspec]
    title = "PAGE TITLE"
    identifier = "inspec/PAGE TITLE"
    parent = "inspec"
    weight = WEIGHT
+++

title is the page title.

gh_repo = "inspec" adds an "[edit on GitHub]" link to the top of each page that links to the Markdown page in the inspec/inspec repository.

[menu.inspec] places the page in the Chef InSpec section of the left navigation menu in <docs.chef.io>. All the parameters following this configure the link in the left navigation menu to the page.

title is the title of page in the Chef InSpec menu.

identifier is the identifier for a page in the menu. It should formatted like this: inspec/RESOURCE NAME. Change PLATFORM to the same value as the platform parameter above. Change RESOURCE NAME to the name of the resource.

parent is the identifier for the section of the menu that the page will be found in. This value is set in the chef-web-docs menu config. Set this value to the section of the InSpec menu that you want the page to located in.

weight sorts the page in the menu relative to other pages. Higher weights are lower in the menu. Pages without a weight are sorted alphabetically by page title.

Resource Pages

All resource pages are located in docs-chef-io/content/inspec/resources/.

InSpec Resources Index Page

The InSpec resources index page is located in docs-chef-io/content/inspec/resources/_index.md and can be found on https://docs.chef.io/inspec/resources/.

The resources on this page are organized by platform. All resources in a platform are added to this page using the inspec_resources shortcode. To add a new group of resources of a specific platform, add the shortcode and specify the platform parameter: {{< inspec_resources platform="PLATFORM" >}}

The inspec_resources shortcode searches for the platform parameter in all pages in the content/inspec/resources directory and then creates a list of those pages that have the specified parameter.

New Resource Pages

Create a new resource page by running hugo new -k resource inspec/resources/RESOURCE_NAME.md from the docs-chef-io directory.

This will create a new resource page with enough content preformatted to get you started.

Resource Page Front Matter

At the top of each resource is a block of front matter that Hugo uses to add a title to each page and locate each page in the left navigation menu in <docs.chef.io>. Below is an example of a page's front matter:

+++
title = "RESOURCE NAME resource"
platform = "PLATFORM"
gh_repo = "inspec"

[menu.inspec]
title = "RESOURCE NAME"
identifier = "inspec/resources/PLATFORM/RESOURCE NAME"
parent = "inspec/resources/PLATFORM"
+++

title is the page title.

platform = PLATFORM sorts each page into the correct category in the Chef InSpec resources list page. Specify the platform that this page should be listed under in the resources list page.

gh_repo = "inspec" adds an "[edit on GitHub]" link to the top of each page that links to the Markdown page in the inspec/inspec repository.

[menu.inspec] places the page in the Chef InSpec section of the left navigation menu in <docs.chef.io>. All the parameters following this configure the link in the left navigation menu to the page.

title is the title of page in the Chef InSpec menu.

identifier is the identifier for a page in the menu. It should formatted like this: inspec/resources/PLATFORM/RESOURCE NAME. Change PLATFORM to the same value as the platform parameter above. Change RESOURCE NAME to the name of the resource.

parent = "inspec/resources/PLATFORM" is the identifier for the section of the menu that the page will be found in. This value is set in the chef-web-docs menu config. Change PLATFORM to the same value as the platform parameter.

Shortcodes

A shortcode is a file with a block of text that can be added in multiple places in our documentation by referencing the shortcode file name.

There are two types of shortcodes: Markdown and HTML.

Add a Markdown shortcode to a page by wrapping the filename, without the .md file suffix, in double curly braces and percent symbols. For example: {{% inspec_filter_table %}}.

Add an HTML shortcode to a page by wrapping the filename, without the .html file suffix, in double curly braces and greater than and lesser than symbols. For example: {{< shortcode_name >}}.

Some shortcodes take parameters; for example, the inspec_resources shortcode requires a platform parameter: {{< inspec_resources platform="PLATFORM" >}}

Local Development Environment

We use Hugo, Go, andNPM to build the Chef Documentation website. You will need Hugo 0.83.1 or higher installed and running to build and view our documentation properly.

To install Hugo, NPM, and Go on Windows and macOS:

• On macOS run: brew install hugo node go
• On Windows run: choco install hugo-extended nodejs golang

To install Hugo on Linux, run:

• apt install -y build-essential
• snap install node --classic --channel=12
• snap install hugo --channel=extended

Preview InSpec Documentation

There are two ways to preview the documentation in inspec:

• submit a PR
• make serve

Submit a PR

When you submit a PR to inspec/inspec, Netlify will build the documentation and add a notification to the GitHub pull request page. You can review your documentation changes as they would appear on docs.chef.io.

make serve

Running make serve will clone a copy of chef/chef-web-docs into docs-chef-io. That copy will be configured to build the InSpec documentation from docs-chef-io and live reload if any changes are made while the Hugo server is running.

• Run make serve
• go to http://localhost:1313

Clean Your Local Environment

If you have a local copy of chef-web-docs cloned into docs-chef-io, running make clean_all will delete the cloned copy of chef-web-docs. Hugo will rebuild everything from scratch the next time you run make serve.

Update the InSpec Docs Content on doc.chef.io

We use Hugo modules to build Chef's documentation from multiple repositories. Expeditor will submit a pull request that updates the documentation in chef/chef-web-docs the next time InSpec is promoted.

The Docs Team can also update the InSpec documentation if changes need to be made before the next promotion.

You can also submit a pull request to chef-web-docs to update the InSpec docs content on docs.chef.io. See the chef-web-docs readme for information on updating a Hugo module in chef-web-docs.

Documentation Feedback

We love getting feedback, questions, or comments.

Email

Send an email to Chef-Docs@progress.com for documentation bugs, ideas, thoughts, and suggestions. This email address is not a support email address. If you need support, contact Chef Support.

GitHub issues

Submit an issue to the InSpec repo for "important" documentation bugs that may need visibility among a larger group, especially in situations where a doc bug may also surface a product bug.

Submit an issue to chef-web-docs for doc feature requests and minor documentation issues.