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 taken from major publishers and related resources. Think of Vale as a personal copyeditor (Wikipedia).

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. You can also create and 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

    This shows how to use Homebrew to install Vale on a Mac.

  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. This downloads the packages specified in the Packages setting.

    $ 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 and specify the filename:

% 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 passive voice

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 and then decide next steps.

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.

Here, 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 style to Packages.

    Packages = Google, proselint, Hugo, alex, Readability

    b. Update BasedOnStyles to include the supplementary style.

    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

Vale is a rich and flexible environment, one that supports many customization opportunities.

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

This section shows three ways to customize Vale for different uses.

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.

    In this example, the Readability package calculates a readability score for README.

Use this to set up validations run at specific points in your workflow, possibly as part of a final review or a milestone checkup. Doing so can reveal insights into your content and provide valuable feedback.

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

Such customizations are sometimes called project styles, as they reflect choices limited to a given project (such as this website).

Use this with care, as each rule was originally selected for good reason.

If you’re using a set of rules to match an organization’s style, work with your contacts to determine available options.

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.

The file reviewed in that sample was the theme’s README file, so it makes sense to add the name to a custom vocabulary.

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:

project-home
└── styles
    └── config
        └── vocabularies
            └── myproject
                ├── accept.txt
                └── reject.txt

Here:

  • project-home is the root folder (or home) of your project
  • myproject is the name of your custom vocabulary
  • accept.txt lists acceptable words; that is, words that aren’t spelling errors
  • reject.txt lists words to be flagged as “Avoid using”

Here’s one way to set this up:

  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 = myproject

    MinAlertLevel = suggestion

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

  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/myproject
% touch styles/config/vocabularies/myproject/accept.txt
% touch styles/config/vocabularies/myproject/reject.txt

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

    Each word should have its own line.

    Words are case-sensitive by default, but this can be configured (Vale.sh).

After setting this up, Vale ignores the words in your accept.txt file and flags the ones in your reject.txt file as terms to avoid.

Use this feature carefully.

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

Evaluate customizations

Take time to evaluate the impact of customization. Vale’s diligence can seem annoying, however, there is also value in catching common mistakes. Try to balance convenience against risk.

It may tempting to turn off a specific rule that routinely flags false positives. Before doing so, consider the impact of letting an embarrassing mistake slip through.

To learn more about Vale customization, 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 deployment pipelines, which can create automation opportunities.

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

Vital statistics

  • 17 August 2025: Minor tweaks and editorial adjustments.
  • 16 August 2025: First post to this site.