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 in the docs/sources
directory.
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
from the docs/
directory.
The output is similar to the following:
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. See also `docs-no-pull`.
docs-no-pull Serve documentation locally without pulling the `DOCS_IMAGE` (default: `grafana/docs-base:latest`) container image.
docs-debug Run Hugo web server with debugging enabled. TODO: support all SERVER_FLAGS defined in website Makefile.
doc-validator Run docs-validator on the entire docs folder.
doc-validator/% Run doc-validator on a specific path. To lint the path /docs/sources/administration, run 'make doc-validator/administration'.
docs.mk Fetch the latest version of this Makefile from Writers' Toolkit.
To lint prose with Vale, run make vale
from the docs/
directory.
Any linting errors are logged by the tool.
Additionally, some repositories run Vale as part of Continuous Integration (CI). Repositories that run Vale in CI include:
Skip rules
To skip a rule, enclose the section with HTML comments that first disable, and then re-enable the specific Vale rule.
To disable the Grafana.Quotes
rule:
<!-- vale Grafana.Quotes = NO -->
The task title is required.
The task title succinctly describes the goal to be accomplished as the result of following the instruction.
The task title contains a verb and an object. For example: "Create a dashboard".
<!-- vale Grafana.Quotes = YES -->
Use Vale in VS Code
You can use Vale to lint your current document in VS Code.
Before you begin
If you are installing Vale on Linux, it may be possible to use the package repositories for your Linux distribution. The manual installation documented below is the preferred way to install Vale on Linux.
Note: The Vale Snap is out of date and not maintained. Don’t install Vale using the Ubuntu Snap store.
If you are installing Vale on macOS, make sure that Homebrew is installed.
If you are installing Vale on Windows, make sure that Chocolatey is installed.
Note: You can download and manually install Vale on Linux, macOS, or Windows. If you manually install Vale, you must configure your system to add Vale to your path or set the Vale › Vale CLI: Path in the Vale VS Code extension configuration.
Install and configure Vale in VS Code
Clone the Writer’s Toolkit repository.
bashgit clone git@github.com:grafana/writers-toolkit.git
Download and install Vale.
Note: Verify that you are downloading the latest build of Vale for Linux. To find the latest builds, refer to Releases - errata-ai/vale.
linux-cliwget https://github.com/errata-ai/vale/releases/download/v2.28.0/vale_2.29.0_Linux_64-bit.tar.gz mkdir bin && tar -xvzf vale_2.29.0_Linux_64-bit.tar.gz -C bin export PATH=./bin:"$PATH"
macosbrew install vale
windowschoco install vale
Create a
vale.ini
file in your home directory or in a working directory with the following contents:bashMinAlertLevel = suggestion StylesPath = /FULL_PATH_TO_REPO/writers-toolkit/vale [*.md] BasedOnStyles = Google, Grafana Google.Quotes = NO Google.Units = NO Google.WordList = NO TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*
Replace
FULL_PATH_TO_REPO
with the full path to the cloned 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
- On Linux, you could set StylesPath to
Install the Vale VS Code extension in VS Code.
- Start VS Code.
- Press Ctrl+P, paste the following command, and press Enter. Alternatively, click the Extensions icon, search for “Vale VS Code”, open it, and click “Install”.
ext install ChrisChinchilla.vale-vscode
Configure the Vale VS Code extension.
- Press Ctrl+Shift+X or click the Extensions icon and select the Vale VS Code extension.
- Select the gear icon.
- Set Vale › Vale CLI: Config to the path to your
vale.ini
file. The path depends on where you created thevale.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
- On Linux, that could be
- 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 unzipped the Vale executable. For example, that could be
/home/<USERNAME>/bin/vale
on Linux.
Restart VS 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.