Vale: Your style, our editor

Vale is a natural language linter that supports plain text, markup (Markdown, reStructuredText, AsciiDoc, and HTML), and source code comments. Vale doesn't attempt to offer a one-size-fits-all collection of rules—instead, it strives to make customization as easy as possible.

Check out project website or our blog post to learn more!

Installation

There are a few options to choose from:

• Homebrew (macOS):

  $ brew tap ValeLint/vale
  $ brew install vale

• Go:

  $ go get github.com/errata-ai/vale

• Docker:

  $ docker pull jdkato/vale

• A Windows Installer package (.msi), which you'll find on the releases page.

• Manually on Windows, macOS, or Linux by downloading an executable from the releases page.

Plugins for other software

• Atom—TimKam/atomic-vale
• Emacs—abingham/flycheck-vale
• Sublime Text—SublimeLinter-contrib-vale
• Visual Studio Code—testthedocs/vscode-vale
• Vim:
  • Via ALE (thanks to @chew-z)
  • Via Neomake

Usage

Using the built-in styles

Vale ships with styles for proselint, write-good, and Joblint. The benefits of using these styles over their original implementations include:

• Improved support for markup, including the ability to ignore code and target only certain sections of text (e.g., checking headers for a specific capitalization style).
• No need to install and configure npm (Node.js), pip (Python), or other language-specific tools. With Vale, you get all the functionality in a single, standalone binary available for Windows, macOS, and Linux.
• Easily combine, mismatch, or otherwise customize each style.

To use one of these styles, you'll need to create a config file alone the lines of the following:

# This goes in a file named either `.vale.ini` or `_vale.ini`.

StylesPath = path/to/some/directory
MinAlertLevel = warning # suggestion, warning or error

# Only Markdown and .txt files; change to whatever you're using.
[*.{md,txt}]
# List of styles to load.
BasedOnStyles = proselint, write-good, Joblint
# Style.Rule = {YES, NO, suggestion, warning, error} to
# enable/disable a rule or change its level.
write-good.E-Prime = NO

See Getting Started for more information.

Creating your own style

While the built-in styles are useful, Vale is really designed to meet custom needs. This is done by using Vale's extension points (called "checks") that can be customized to perform many different kinds of tasks, including calculating readability, measuring sentence length, and enforcing a particular heading style.

See the Microsoft project for a complete example of a Vale-compatible style guide.

Using the CLI

Run Vale on a single file:

$ vale README.md

Run Vale on files matching a particular glob:

# Only lint Markdown and reStructuredText
$ vale --glob='*.{md,rst}' directory

Or exclude files matching a particular glob:

# Ignore all `.txt` files
$ vale --glob='!*.txt' directory

Pipe input to Vale:

$ echo 'this is some very interesting text' | vale

Run Vale on text with an assigned syntax:

$ vale --ext=.md 'this is some `very` interesting text'

See vale --help and Usage for more information.

Say thanks

Hi!

My name is Joseph Kato.

In my spare time, I develop and maintain a few open-source tools for collaborative writing.

If you'd like to support my work, you can donate via Square's Cash App or make use of my documentation-related consulting services. Alternatively, I'd greatly appreciate a simple note explaining how you're using my software (which you can send via the 'Say Thanks' project).

I appreciate the support! Thank you!