Harnessing Vale

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:

1. 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.
2. Download the Vale VS Code extension.
   1. Ensure that VS Code is installed on your system.

Project setup

1. Construct a file named .vale.ini in 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

2. Run 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.

Customize rules

1. Create a fresh folder within the vale/styles directory for your unique rules.

For example, for a company named Company-name, the command would be mkdir vale/styles/Company-name.

2. In this new folder, create a terms.yml file with your specific linting guidelines. Here is a sample rule set:

extends: substitution
message: Consider using '%s' instead of '%s'
link: 'www.internal-tools.io'
level: warning
ignorecase: false
action:
 name: replace
# swap maps tokens in the form of bad: good
swap:
   applications: apps
   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: vale hello.md.

You’ll see an output that describes what to fix either by error, warning, or suggestion and the fixes needed to apply.

Next steps

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.