Chef Infra Client docs

Documentation for Chef Infra Client.

Versions

The content in this repo is versioned using different Git branches.

When we get version numbers for those releases, that content will be moved into release-<VERSION_NUMBER> branches.

Configuration

The version is configured in two ways:

• the branch name, which uses the following pattern release-<MAJ>.<MIN>
• the version number, which is set by the product_version parameter in the root _index.md file.

Style guide

See the Chef Documentation style guide for writing and formatting guidance. If you don't find style guidance in the Chef Documentation Style Guide, use Google's Style Guide or Microsoft's Style Guide.

Shortcodes

We have a variety of shortcodes for including content and formatting pages and text.

Links

Use the relref shortcode to add relative links to pages or sections within this documentation set.

Examples:

• [link text]({{< relref "some_page" >}})
• [link text]({{< relref "section/some_page" >}})
• [link text]({{< relref "section/some_page#heading-id" >}})

Images

Add images to static/images/.

Alt text

All images must have alt text. See the W3C WAI guidelines for alt text.

Example:

![alt text](static/images/image.png)

Images of text

Don't add images of text, for example, images of configuration files, code samples, or terminal outputs. People who use screen readers can't read an image of text and users may want to copy and paste that text on their workstation.

Add code examples, terminal outputs, or config files as a code block.

Local development

Requirements

• Hugo 0.123.4 or greater
• Node 10.0.0 or higher
• NPM 5.6.0 or higher
• Go 1.22 or higher
• Dart Sass 1.72 or higher

To install on Windows, run:

choco install hugo-extended nodejs golang sass

To install on macOS, run:

brew install hugo node go sass/sass/sass

To install on Ubuntu, run:

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

Build and preview the docs locally

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

Editing tools

Use the following extensions for editing in VSCode:

• Code Spell Checker
• Markdownlint
• Trailing Spaces
• Vale

Build and preview using Netlify CLI

You can use the Netlify CLI to build and preview documentation locally. This is useful for previewing redirects or other settings configured in the netlify.toml file.

Requirements:

• all the requirements for building this site locally
• Netlify CLI

Run netlify dev to preview the site using the Netlify CLI.

Netlify deployment

Netlify deploys content in the main branch of this repository to https://chef-infra-client.netlify.app/.

Versioning

1. Create a branch of this repo in the following format: release-<MAJ>.<MIN>.

2. On the Netlify site add a branch deploy for that branch in the site configuration.

3. Push the branch up to GitHub. Netlify automatically builds a deployment of that branch at release-<MAJ>.<MIN>--chef-infra-client.netlify.app/client/<MAJ>.<MIN>. Any changes merged into that branch are automatically deployed.