vale

README

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 to learn more!

Highlights

• Supports Markdown, reStructuredText, AsciiDoc, HTML, and source code.
• Extensible through straightforward YAML files.
• Standalone binaries for Windows, macOS, and Linux.
• Expressive, EditorConfig-like configuration.

Features

Vale's functionality is split into extension points (called "checks") that can be customized to perform many different kinds of tasks, including finding insensitive words and phrases, measuring sentence length, enforcing a particular heading style, and identifying undefined acronyms. See the Style Showcase for more complete examples.

Additionally, since Vale is "syntax aware," you'll never have to worry about syntax-related false positives (e.g., URLs or code blocks). See Creating a style for more information.

Installation

There are a few options to choose from:

• Homebrew on macOS:

  $ brew tap ValeLint/vale
  $ brew install vale
  

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

• Chocolatey on Windows (thanks to @Kristinita):

  C:\> choco install vale
  

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

Usage

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 text' | vale

Run Vale on text with an assigned syntax:

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

See vale --help and Configuration for more information.

Integrations

• Atom—TimKam/atomic-vale
• Sublime Text—ValeLint/SubVale
• Vim—via ALE (thanks to @chew-z)

Reference Styles

Style (source)	Download	Description	Development Status
write-good	write-good.zip	Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.	✅
Joblint	Joblint.zip	Test tech job posts for issues with sexism, culture, expectations, and recruiter fails.	✅
jQuery	jQuery.zip	A collection of rules based on jQuery's documentation formatting conventions and writing style.	🚧
TheEconomist	TheEconomist.zip	A collection of rules based on The Economist Style Guide.	🚧
Homebrew	Homebrew.zip	A set of style and usage guidelines for Homebrew’s prose documentation aimed at users, contributors, and maintainers.	🚧
Middlebury	Middlebury.zip	A collection of rules based on The Middlebury Editorial Style Guide.	🚧
18F	18F.zip	Guidelines for creating plain and concise writing.	🚧

To use one of these styles, you'd copy its files onto your StylesPath and then specify it in your config file:

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

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

[*.{md,txt}] # Only Markdown and .txt files
# List of styles to load
BasedOnStyles = vale, Joblint
# Style.Rule = {YES, NO, suggestion, warning, error} to
# enable/disable a rule or change its level.
vale.Editorializing = NO

See Configuration and Styles for more information.