Documentation Writers' Toolkit Build and review Lint prose

Lint prose with the Vale linter

Vale is a syntax-aware linter for prose built with speed and extensibility in mind.

Every project keeps technical documentation that’s published to the website in the docs/sources directory. That documentation is published to the content/docs directory in the website repository.

Additionally, every project uses GNU Make to perform tasks related to technical documentation. To learn more about GNU Make, refer to GNU Make Manual.

To see a list of targets and their descriptions, run make help from the docs/ directory. If you are in the website repository, run make help from the root of the repository instead.

The output is similar to the following:

console Copy

Usage:
  make <target>

Targets:
  help             Display this help.
  docs-rm          Remove the docs container.
  docs-pull        Pull documentation base image.
  make-docs        Fetch the latest make-docs script.
  docs             Serve documentation locally, which includes pulling the latest `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image. To not pull the image, set `PULL=false`.
  docs-debug       Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
  doc-validator    Run doc-validator on the entire docs folder which includes pulling the latest `DOC_VALIDATOR_IMAGE` (default: `grafana/doc-validator:latest`) container image. To not pull the image, set `PULL=false`.
  vale             Run vale on the entire docs folder which includes pulling the latest `VALE_IMAGE` (default: `grafana/vale:latest`) container image. To not pull the image, set `PULL=false`.
  update           Fetch the latest version of this Makefile and the `make-docs` script from Writers' Toolkit.

To lint prose with Vale, run make vale from the docs/ directory. The tool prints linting errors to your terminal.

Additionally, some repositories run Vale as part of Continuous Integration (CI). Repositories that run Vale in CI include:

• Grafana website
• Writers’ Toolkit

Skip rules

To skip a rule, enclose the section with HTML comments that first disable, and then re-enable the specific Vale rule. Include the specific rule name in the comment, for example Grafana.We or Grafana.GoogleEllipses. The following example shows how to disable the Grafana.GooglePassive rule:

markdown Copy

<!-- vale Grafana.GooglePassive = NO -->

- [Deprecated content](#deprecation-example): Features that have been deprecated, but still need to be documented for some time.
- [Configuration options](#configuration-options-example): Features that have several ways they can be configured.

<!-- vale Grafana.GooglePassive = YES -->

Use Vale in Visual Studio Code

You can use Vale to lint your current document in Visual Studio Code.

Before you begin

If you are installing Vale on Linux, you may be able to install Vale from the package repositories for your Linux distribution. However, the following manual installation instructions are the preferred way to install Vale on Linux.

If you are installing Vale on macOS, first install Homebrew.

If you are installing Vale on Windows, first install Chocolatey.

Install and configure Vale in Visual Studio Code

1. Clone the Writer’s Toolkit repository.

   bash Copy

   git clone git@github.com:grafana/writers-toolkit.git

   If you have previously cloned the repository, run git pull on the main branch.

2. Download and install Vale.

   Note

   Verify that you are downloading the most recent build of Vale for Linux. To find the most recent build, refer to Releases - errata-ai/vale.

   linux-climacoswindows

   Copy

   linux-cli Copy

   wget https://github.com/errata-ai/vale/releases/download/v3.1.0/vale_3.1.0_Linux_64-bit.tar.gz
   mkdir bin && tar -xvzf vale_3.1.0_Linux_64-bit.tar.gz -C bin
   export PATH=./bin:"$PATH"

   macos Copy

   brew install vale

   windows Copy

   choco install vale

3. Create a .vale.ini file in your home directory or in a working directory with the following contents:

   bash Copy

   MinAlertLevel = suggestion
   StylesPath = /<PATH TO WRITERS TOOLKIT REPOSITORY>/vale
   
   [*.md]
   BasedOnStyles = Grafana
   TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*

   Replace <PATH TO WRITERS TOOLKIT REPOSITORY> with the full path to your checkout of the Writer’s Toolkit repository. The path depends on where you cloned the Git repository. For example:

   • On Linux, you could set StylesPath to /home/<USERNAME>/git-repos/writers-toolkit/vale
   • On macOS, you could set StylesPath to /Users/<USERNAME>/git-repos/writers-toolkit/vale
   • On Windows, you could set StylesPath to C:\Users\<USERNAME>\git-repos\writers-toolkit\vale

4. Install the Vale Visual Studio Code extension in Visual Studio Code.

   1. Start Visual Studio Code.

   2. Press Ctrl+P, paste the following command, and press Enter. Alternatively, click the Extensions icon, search for “Vale VSCode”, open it, and click Install.

      Copy

      ext install ChrisChinchilla.vale-vscode

5. Configure the Vale Visual Studio Code extension.

   1. Press Ctrl+Shift+X or click the Extensions icon and select the Vale Visual Studio Code extension.
   2. Select the gear icon.
   3. To use your own Vale configuration for all repositories, set Vale › Vale CLI: Config to the path to your .vale.ini file. The path depends on where you created the .vale.ini file. For example:
      • On Linux, that could be /home/<USERNAME>/.vale.ini
      • On macOS, that could be /Users/<USERNAME>/.vale.ini
      • On Windows, that could be C:\Users\<USERNAME>\.vale.ini
   4. For manual installations on Linux, macOS, or Windows, set Vale › Vale CLI: Path to the path for the Vale executable. The path depends on where you extracted the Vale executable. For example, that could be /home/<USERNAME>/bin/vale on Linux.

6. Restart Visual Studio Code.

Vale lints your current document every time you save your changes. The extension reports the linting results in two ways:

• In-line edit marks. You can hover your mouse cursor over the edit marks to view the Vale warning or error.
• A full report in the PROBLEMS tab. Each Vale warning or error in the report includes the line and column where the error occurs.