DataDog / datadog-vale

Documentation Style Guide for the Vale Linter. Owned and maintained by the Datadog Docs team.

Overview

The Datadog Documentation team implements, maintains, and owns a style guide utilizing the Vale Linter. This repository contains a set of linting rules for Vale based on the Documentation Style Guide.

Setup

1. Clone this repository.
2. Install Vale with brew install vale (macOS) or choco install vale (Windows).
3. Set the StylesPath parameter to styles/Datadog in your .vale.inifile.
4. Run vale . from the root folder of the repository, or specify a file to lint on using vale /path/to/some/directory.

Usage

Rules are stored in YAML files, and you can set Docshtml to lint on HTML, and Docsmd to lint on Markdown files in your .vale.ini file. Make sure all files are lowercase.

For example, this gender.yml rule raises an error when Vale detects a gendered pronoun in a Markdown file:

extends: existence
message: "Use a gender-neutral pronoun instead of '%s'."
link: "https://github.com/DataDog/documentation/blob/master/CONTRIBUTING.md#gender"
level: error
ignorecase: true
tokens:
  - he/she

The files in this repository contain settings for the Vale linter (defined in .vale.ini) and style rules published by the Datadog Docs team (defined in styles/Datadog). These can be used as a GitHub Action or locally.

GitHub Action

1. Add the example linting.yml file to your repository's .github/workflows folder.
2. (Optional) Update linting.yml styles and config files as necessary.
3. (Optional) Add your custom .vale.ini file to your repository's root directory.

Example of linting with GitHub Actions:

Local

1. Install Vale locally.
2. Optional for VS Code users:
   • Install vale-vscode through the Marketplace.
   • Set vale.core.useCLI to true in the Extension Settings (Preferences > Extensions > Vale > Use CLI).
   • Restart VS Code.
3. Download the latest release of the source code.
4. Unzip the file to your local repository's .github/styles folder.
5. Add a .vale.ini file to your repository's root directory.
6. Update your .gitignore:

   # Vale
   .github/styles  # required if the repo uses GitHub Actions
   .vale.ini       # optional
   

Example of local linting with VS Code:

License

Code—including sample code—in this repository is licensed under the Apache 2.0 license.