Skip to main content

Developing Documentation

[edit on GitHub]

This document covers the tools used by the @chef-docs team for developing documentation.

GitHub

If you do not already have one, set up your GitHub account.

Download and install Git onto your computer from git-scm.com

Configure Git: First time setup

After you have Git setup, create a directory for your repositories. Some name this directory code or repos. Use whatever name makes sense for you.

Homebrew

Homebrew is a package manager for macOS. Install Homebrew with the command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew tap go-swagger/go-swagger chef/okta-aws && brew install go-swagger okta-aws hugo node go jq direnv readline openssl@1.1 gh vale vagrant virtualbox coreutils gnutls

This command installs

Chocolatey

Install Chocolatey

choco install choco install hugo-extended nodejs golang jq  gh

Install Docker Desktop Install go-swagger

  • Download the Docker image: docker pull quay.io/goswagger/swagger
  • Run with: docker run --rm -it --env GOPATH=/go -v %CD%:/go/src -w /go/src quay.io/goswagger/swagger

Visual Studio Code (VSCode)

Microsoft’s VSCode is a free and open source editor. VSCode offers many extensions–including a Chef extension–that provide useful language and documentation support.

Install VSCode

Learn a bit about VSCode through Microsoft Learn Videos and tutorials.

Install the extensions:

  • Docs Authoring Pack (includes Code Street Spell and Markdownlint, adds some automatic configuration.)

  • Code Street Spell

  • Markdownlint

  • Vale

  • Better TOML

  • YAML

  • GitHub Pull Requests and Issues

  • Chef Extension for Visual Studio Code

  • LiveShare

Code Spell Checker

Clone the Chef Dictionary into your repository directory

gh repo clone chef/chef_dictionary

Navigate to your VSCode settings by selecting the gear icon at the bottom left side of the VSCode screen and find the Code Spell settings. Open the setting for “C Spell Dictionaries” and add the following content, adjusting the path for your local workstation

  "cSpell.dictionaryDefinitions": [
  { "name": "chef_dictionary",
    "path": "/Users/<username>/<repodir>/chef_dictionary/chef_dictionary/chef.txt"}
  ],
  "cSpell.dictionaries": [
    "chef_dictionary"
  ],

Add this configuration to exclude code blocks from spellcheck:

  "cSpell.languageSettings": [
    {  // use with Markdown files
      "languageId": "markdown",
      // Exclude code blocks from spellcheck.
      "ignoreRegExpList": [
          "/^\\s*```[\\s\\S]*?^\\s*```/gm"
      ]
    }
  ]

Markdownlint

Markdownlint-CLI2 is a fast, flexible, configuration-based command-line interface for linting Markdown files.

Install the Markdownlint CLI into your local environment:

npm install markdownlint-cli2 --global

chef/chef-web-docs/.markdownlint.yaml is the configuration file with the Markdown rules for Chef documentation files.

This is a full list of Markdownlint rules

To enable or disable rules for specific lines, add the appropriate marker:

  • Disable all rules: <!-- markdownlint-disable -->
  • Enable all rules: <!-- markdownlint-enable -->
  • Disable all rules for the next line only: <!-- markdownlint-disable-next-line -->
  • Disable one or more rules by name: <!-- markdownlint-disable MD001 MD005 -->
  • Enable one or more rules by name: <!-- markdownlint-enable MD001 MD005 -->
  • Disable one or more rules by name for the next line only: <!-- markdownlint-disable-next-line MD001 MD005 -->
  • Capture the current rule configuration: <!-- markdownlint-capture -->
  • Restore the captured rule configuration: <!-- markdownlint-restore -->

To enable or disable rules for entire files, use:

  • Disable all rules: <!-- markdownlint-disable-file -->
  • Enable all rules: <!-- markdownlint-enable-file -->
  • Disable one or more rules by name: <!-- markdownlint-disable-file MD001 -->
  • Enable one or more rules by name: <!-- markdownlint-enable-file MD001 -->

For more information about customizing Markdownlint, see the Markdownlint GitHub Repository README.

Vale

Vale

# Example Vale config file (`.vale.ini` or `_vale.ini`)

# Core settings
StylesPath = /Users/kimberlygarmoe/repos/styles

# The minimum alert level to display (suggestion, warning, or error).
#
# CI builds will only fail on error-level alerts.
MinAlertLevel = warning

# By default, `code` and `tt` are ignored.
IgnoredScopes = code, tt, script

# SkippedScopes specifies block-level HTML tags to ignore. Any content in these scopes will be ignored.
SkippedScopes = script, style, pre, figure

# WordTemplate specifies what Vale will consider to be an individual word.
WordTemplate = `\b(?:%s)\b`

# BlockIgnores allow you to exclude certain block-level sections of text that don't have an associated HTML tag that could be used with SkippedScopes. See Non-Standard Markup for more information.
# BlockIgnores = (?s) *({< file [^>]* >}.*?{</ ?file >})
# Ignore code fences
BlockIgnores = (((\x60{3}){1,1})([\s\S]*?)((\x60{3}){1,1}))

# TokenIgnores allow you to exclude certain inline-level sections of text that don't have an associated HTML tag that could be used with IgnoredScopes. See Non-Standard Markup for more information.
# TokenIgnores = (\$+[^\n$]+\$+)
# Ignore SVG markup
TokenIgnores = (\*\*\{\w*\}\*\*)

# The "formats" section allows you to associate an "unknown" format
# with one of Vale's supported formats.
[formats]
mdx = md
proto = md

# Global settings (applied to every syntax)
[*]

Vocab = chef_dictionary
# List of styles to load
BasedOnStyles = write-good, vale-chef
# Chef, Microsoft
# Style.Rule = {YES, NO} to enable or disable a specific rule
write-good.Editorializing = YES
# Microsoft.Contractions = NO
# You can also change the level associated with a rule
write-good.Hedging = warning

# Syntax-specific settings
# These overwrite any conflicting global settings
[*.{md,txt}]

Download the Chef Repositories

Clone the following repositories:

Product GitHub Docs Directory
Chef Automate [https://github.com/chef/automate
Chef Habitat https://github.com/habitat-sh/habitat
Chef Infra Client https://github.com/chef/chef-web-docs
Chef Infra Server https://github.com/chef/chef-server
Chef Inspec https://github.com/inspec/inspec

For example, you can clone a repo using the GitHub CLI with the command gh repo clone chef/chef-web-docs.

Was this page helpful?

×









Search Results