Vale: a prose linter

A command-line tool that validates content against a set of known rules. Think of it as your personal style checker.

  7 minute read  

Vale is a style-guide validator that helps you write better content.

When run from a command-line, it checks your work against a set of selected rules and highlights potential problems. In writing terms, Vale enforces style guidelines takes from major publishers and related resources. Think of Vale as a personal copyeditor.

More formally, Vale is a linter. Developers use linters to make sure their code follows predetermined guidelines. Vale performs a similar task. You can use it to check content written in Markdown, AsciiDoc, Restructured Text (RST), HTML, and more.

By default, Vale supports three major style guides:

  • Google developer doc style guide
  • Microsoft Writing style guide
  • Red Hat documentation style guide

Vale also supports supplementary style guides and you can customize rules to match your preferences.

Quick setup

The Vale docs provide detailed installation instructions (Vale.sh) for a variety of options, including Docker. However, they can be a bit hard to follow.

For an individual writer, the typical installation process is:

To install and set up Vale:

  1. Use your system’s package manager (Vale.sh) to install Vale.

    $ brew install vale

  2. Use the Vale Config Generator (Vale.sh) to create an initial configuration.

    If you’re not sure which options to choose, consider:

    • Base style: Google developer doc style guide
    • Supplemental style guide: proselint
    • Configuration: As appropriate for your project.

  3. In the home directory for your project, create a hidden configuration file named .vale.ini

    $ cd ~/work/myproject
$ touch .vale.ini

  4. Update your configuration file with the generated configuration.

    StylesPath = styles

MinAlertLevel = suggestion

Packages = Google, proselint, Hugo, alex, Readability

[*.{md}]
BasedOnStyles = Vale, Google, proselint, alex, Readability

  5. Sync Vale to your project settings, which downloads your packages.

    $ vale sync
SUCCESS  Synced 5 package(s) to '~/work/myproject/styles'

When the sync completes, Vale is ready to check your work.

Checking a file

To check a single file, run vale specify the file:

% vale README.md 

README.md
1:3      warning     'Docsy Example' should use      Google.Headings       
                     sentence-style capitalization.                        
1:3      error       Did you really mean 'Docsy'?    Vale.Spelling         
3:2      error       Did you really mean 'Docsy'?    Vale.Spelling         
4:46     error       Did you really mean 'Docsy'?    Vale.Spelling         
4:79     error       Did you really mean 'Docsy'?    Vale.Spelling         
5:22     error       Did you really mean 'hugo'?     Vale.Spelling         
8:22     error       Did you really mean 'Docsy'?    Vale.Spelling         
8:34     suggestion  In general, use active voice    Google.Passive        
                     instead of passive voice ('is                         
                     pulled').

In this partial result, Vale:

  • Reports a capitalization issue with a header
  • Highlights words it doesn’t recognize (Docsy and hugo)
  • Suggests fixing a passive voice use

The numbers on the left report the location of the problem in your source file. The first value is the line number and the second reports the character position.

The value on the right reports the package and name of the rule, which helps with later configuration.

You probably won’t fix every reported problem. You should at least investigate then decide what to do.

Checking multiple files

Use the glob parameter to check multiple files:

% vale --glob="**/*.md" content/
// details removed
✖ 86 errors, 32 warnings and 52 suggestions in 85 files.

In this example, Vale recursively scans the content folder and reports issues in each Markdown file.

Supplementary styles

Vale supports a variety of supplementary style packages, which include:

To add and use a supplementary style:

  1. Update your Vale configuration:

    a. Add the supplementary styles to Packages.

    Packages = Google, proselint, Hugo, alex, Readability

    b. Update BasedOnStyles to include the supplementary styles and their precedence.

    BasedOnStyles = Vale, Google, proselint, alex, Readability

  2. Sync your Vale packages

    $ vale sync
SUCCESS  Synced 5 package(s) to '~/work/myproject/styles'

  3. Test your content

Many organizations publish Vale packages for their in-house style guides.

To see what’s available:

Customizing Vale

You can customize Vale so it adjusts to your personal style or to keep it from flagging valid content.

Alternate rulesets

Use the config parameter to run Vale with a different set of rules.

To do so:

  1. Create an alternate configuration file

    StylesPath = styles
Packages = Readability

[*.{md}]
BasedOnStyles = Readability

  2. Use the --config parameter to specify the alternate configuration file:

    % vale --config=".readability.ini" README.md

 README.md
 1:1  warning  Try to keep the LIX score       Readability.LIX               
               (35.90) below 35.                                             
 1:1  warning  Try to keep the SMOG grade      Readability.SMOG              
               (10.01) below 10.                                             
 1:1  warning  Try to keep the Coleman–Liau    Readability.ColemanLiau       
               Index grade (9.06) below 9.                                   
 1:1  warning  Try to keep the Flesch–Kincaid  Readability.FleschKincaid     
               grade level (8.02) below 8.                                   
 1:1  warning  Try to keep the Flesch reading  Readability.FleschReadingEase 
               ease score (61.88) above 70.                                  

✖ 0 errors, 5 warnings and 0 suggestions in 1 file.

    This example uses the Readability package to calculate a readability score.

Use this to set up validations run at specific points in your workflow, possibly as part of a final review or a milestone checkup.

For best results, use your primary configuration to manage and update packages. Declare them as part of the Packages setting, exclude them from your primary BasedOnStyles, and then create alternate configurations to run on demand. They’ll update when you sync your primary configuration.

Rule adjustments

You can use the configuration file to turn off individual rules.

For example, the following configuration deactivates two rules specified by the Google Developer Doc style guide.

## Project style overrides
Google.FirstPerson = NO
Google.We = NO

Custom vocabulary

Vale includes a partial spell check and flags words it doesn’t recognize. For example, the earlier single file example included warnings about “Docsy,” the name of the theme used in this site.

You can define a custom vocabulary that defines terms that should not be flagged as potential spelling errors.

To do so, you need to create a specific set of folders and files in your Vale styles folder:

  1. Make sure you’re in the directory containing your Vale styles folder.

    % cd ~/work/myproject

  2. Update .vale.ini to define a folder for your custom vocabulary.

    StylesPath = styles
    Vocab = mysite

    MinAlertLevel = suggestion

    Packages = Google, proselint, Hugo  
    // remaining lines deleted

Here, the Vocab setting defines mysite as a custom vocabulary for this project.

  1. In your styles/config/vocabularies folder, create a folder for your custom vocabulary and then create a called accept.txt:

    % mkdir styles/config
% mkdir styles/config/vocabularies
% mkdir styles/config/vocabularies/mysite
% touch styles/config/vocabularies/mysite/accept.txt
% touch styles/config/vocabularies/mysite/reject.txt

    To flag words as problems, add them to reject.txt.

  2. Next, add the word Docsy to accept.txt file.

    When adding new words, put each word on its own line.

    Each word is case-sensitive by default.

At this point, Vale ignores the use of the word Docsy in this project.

Use this feature carefully.

To learn more about how Vale handles custom vocabularies, see Vocabularies (Vale.sh).

Evaluate customizations

Effective customization takes time.

For best results, take time to review customization results and see how they impact your work.

Try to balance convenience against risk.

It may tempting to turn off a test that routinely flags false positives. If an embarrassing mistake slips through as a result, consider reversing the change.

Vale is a rich and detailed environment, one that supports may customization opportunities.

Start by exploring Vale’s:

Editor integration

You can integrate Vale into popular editors, such as IntelliJ, Sublime Text, Visual Studio Code (VSC), and more.

When you integrate Vale into an editor, the built-in style checking provides real-time feedback about potential issues as you type.

You can also incorporate Vale into CI/CD pipelines.

To learn more, see Vale’s Language Server (LSP) (Vale.sh) docs

Vital statistics

  • 16 August 2025: First post to this site.