Vale is a syntax-aware linter
In this document, you’ll learn about Vale and how to apply it to your own documentation.
Visit https://developers.google.com/style for a plethora of grammar resources.
Explore Vale: The Syntax-Aware Linter
Vale stands out as a syntax-aware linter, meaning it empowers you to set guidelines for diverse textual elements such as headings, titles, sentences, and even code snippets.
Setting up Vale
To begin working with Vale, please adhere to the following steps:
- Download the Vale CLI.
1. You’ll need homebrew on MacOS:
/bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"2. Install Vale by running
brew install vale.
1. To update the linter, execute the following:
brew update && brew upgrade vale.
- Download the Vale VS Code extension.
1. Ensure that VS Code is installed on your system.
- Construct a file named
.vale.iniin your project’s root directory and fill it with the following content:
StylesPath = vale/styles
MinAlertLevel = suggestion
Packages = Google, proselint, Hugo
BasedOnStyles = Vale, Google, proselint
vale sync in your project’s root directory.
This will generate a `vale/styles` directory within your project, comprising style folders such as Vale and Google.
- Create a fresh folder within the
vale/stylesdirectory for your unique rules.
For example, for a company named
Company-name, the command would be
2. In this new folder, create a
terms.yml file with your specific linting guidelines. Here is a sample rule set:
message: Consider using '%s' instead of '%s'
# swap maps tokens in the form of bad: good
internal tools: Internal Tools
3. Next, revise your
.vale.ini file to incorporate your recently generated style:
BasedOnStyles = Vale, Google, proselint, Company-name
4. Finally, create a markdown file, for instance,
hello.md, like this:
# Hello World!?!
Hello world world. You can use your internal tools too build your own production grade applications.
To scan your file for any violations, use the
vale command followed by your filename:
You’ll see an output that describes what to fix either by error, warning, or suggestion and the fixes needed to apply.
Continue iterating on your rules and expand your styling.
You can also explore the Package Hub which contains other rules and style guides you can include to enforce.