Developing Documentation
This document covers the tools used by the @chef-docs team for developing documentation.
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 && brew install go-swagger hugo node go vale git
This command installs:
Chocolatey
Install Chocolatey
choco install choco install hugo-extended nodejs golang jq git
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.
- Setup Guide: Visual Studio Code on macOS
- Setup Guide: Visual Studio Code on Windows
- User Interface
- Integrated Terminal
- Getting started with Visual Studio Code Videos
- Working with GitHub in VS Code
- Introduction to GitHub in Visual Studio Code
Install the extensions:
- Docs Authoring Pack (includes Code Street Spell and Markdownlint, adds some automatic configuration.)
- Grammarly
- Trailing Spaces
- Code Street Spell
- Markdownlint
- Vale
- Better TOML
- YAML
- GitHub Pull Requests and Issues
- Chef Extension for Visual Studio Code
- LiveShare
Code Spell Checker
We use CSpell dictionaries that are hosted in the chef_dictionary GitHub repository.
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. In the left menu nav, select Language and Dictionaries, scroll down to C Spell: Dictionary Definitions, select Edit in settings.json, and add the following content in settings.json
file:
"cSpell.dictionaryDefinitions": [
{
"name": "chef",
"path": "https://raw.githubusercontent.com/chef/chef_dictionary/main/chef.txt",
"description": "Custom Chef Dictionary"
},
{
"name": "docs",
"path": "https://raw.githubusercontent.com/chef/chef_dictionary/main/docs.txt",
"description": "Custom Docs Dictionary"
}
]
Add this configuration to the settings.json
file 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.