Home Settle down Vale linting

Vale linting

Vale is an open-source, command-line tool that brings your editorial style guide to life.

Install Vale

You can install Vale on Windows and macOS using several methods:

Use package managers

  • Windows

    Open Windows Terminal and run the following command to install Vale using Chocolatey:

choco install vale

  • macOS

    Open Terminal and run the following command to install vale on Mac using HomeBrew:

brew install vale

Get GitHub releases

There are archives of precompiled binaries that are available for Windows, macOS and Linux. To use one of these, download the archive for your platform, extract it to a local directory and (optionally) add the extracted directory to your $PATH.

For Linux, you can proceed as follows:

wget https://github.com/errata-ai/vale/releases/download/v2.15.4/vale_2.15.4_Linux_64-bit.tar.gz

mkdir bin && tar -xvzf vale_2.15.4_Linux_64-bit.tar.gz -C bin

export PATH=./bin:"$PATH"

For 64-bit Windows, proceed as follows:

wget https://github.com/errata-ai/vale/releases/download/v2.24.4/vale_2.24.4_Windows_64-bit.zip

mkdir bin && tar -xvzf vale_2.24.4_Windows_64-bit.zip -C bin

export PATH=./bin:"$PATH"

For more information, click installation on the Vale’s official website.

Configure Vale

Create a file named .vale.ini in the folder where your text files are stored (the en folder in our projects) and paste the following code into it:

StylesPath = styles

Vocab =

MinAlertLevel = suggestion

[*.rst]
BasedOnStyles = B2broker, Google

Run the following command to download all the packages referenced in the config file:

vale sync

Run Vale

You are now ready to use Vale with the default configuration. Run the following command to start linting a markdown file:

vale README.md

Check through a sample repository

To get started, you can proceed as follows to run your first check using Vale:

git clone git@github.com:errata-ai/vale-boilerplate.git && cd vale-boilerplate

vale sync

vale README.me

Congratulations! If you can see these lines, it means that you have successfully run your first check using Vale.

_images/first.png

Let’s take a look at the project structure. As the following image illustrates, there is a style folder containing all the packages referenced in your INI file. These are predefined style guides that you can use within your project. You can also create your own style guides.

_images/style.png

Add custom style guides

Let’s add a custom rule to check for occurrences of will or must in our texts as follows:

  1. Create a folder inside the style folder of your project:

_images/structure.png

  1. As an example, create a YAML file named will-must.yml and paste the following code into it:

extends: existence
message: "Avoid using '%s'."
ignorecase: true
level: warning
tokens:
 - will
 - must

  1. Run the following command:

vale your-file.rst

Let’s check this sample YAML file line by line:

1. extends

Imports the required extension to check for occurrence of a specific term or statement.

Here is a list of all extensions that are used in Vale:

Name

Description

capitalization

Checks whether the text in a given scope matches the specified case.

conditional

Ensures that the occurrence of the first term necessitates the occurrence of the second term.

consistency

Ensures that a key and its value (such as advisor and adviser) don’t occur in a given scope simultaneously.

existence

This is the most general extension point. As its name implies, it looks for occurrence of particular tokens.

occurrence

Enforces the maximum or minimum number of times a specific token can appear in a given scope.

repetition

Looks for repeated occurrences of its tokens.

substitution

Associates a string with a preferred form.

spelling

Performs spell checking using Hunspell-compatible dictionaries.

sequence

While most extension points focus on the writing style, sequence aims to support grammar-focused rules.

metric

Enforces arbitrary formulas using pre-defined, built-in variables.

script

Allows you to create arbitrary logic-based rules using Tengo, a Go-like scripting language.

2. message

The message that is displayed when there is anything that should be corrected. You can also use format specifiers, such as %s.

3. ignorecase

A boolean variable indicating whether the search is case-sensitive.

4. level

Specifies the linting level, which can be one of the following:

  • suggestion

  • warning

  • error

5. tokens

An array of terms, statements and regular expressions that are searched for in our texts.

Learn more

https://vale.sh/

https://github.com/errata-ai/vale

https://blog.meilisearch.com/prose-linting-with-vale/

https://medium.com/valelint/introducing-vale-an-nlp-powered-linter-for-prose-63c4de31be00

https://docsy-site.netlify.app/docs/vale/vale-styleguides/

https://docs.gitlab.com/ee/development/documentation/testing.html

https://getstream.io/blog/linting-documentation-with-vale/

https://www.youtube.com/watch?v=gAOgvGFEBtY

https://docs.gitlab.com/ee/development/documentation/testing.html#vale