Vale: Your Style, Our Editor

🌟 We're now offering Integration Assistance! This is a great way to support the project while also getting the time-consuming tasks (e.g., creating a Vale-compatible version of your house style or setting up a CI service) out of the way.

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—lunaryorn/vscode-vale
• Vim—via ALE (thanks to @chew-z)

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

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 vale-boilerplate repository for a complete example of using Vale to enforce an external editorial 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 PayPal or make use of my consulting services.

PayPal	Consulting
Donate with PayPal	Tell us what you need

I appreciate your support! Thank you!