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 meet your own needs:

• existence (example): As its name implies, it looks for the existence of particular strings. This is useful if, for example, we want to discourage the use of a certain word or phrase.
• substitution (example): This is similar to above, but it also suggestions a preferred form. For example, we'd use this if we want to suggest the use of “plenty” instead of “abundance.”
• occurrence (example): This limits the number of times a particular token can appear in a given scope. For example, if we’re limiting the number of words per sentence.
• repetition (example): This checks for repeated occurrences of its tokens (e.g., lexical illusions like “the the”).
• consistency (example): This will ensure that a key and its value (e.g., “advisor” and “adviser”) don’t both occur in its scope.
• conditional (example): This ensures that the existence of first implies the existence of second. This is useful for things like verifying that an abbreviation has a parenthetical defintion.
• spelling (example): This will spell check against a large list of words accounting for customizations (e.g., removing or adding words to the dictionary).

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:

• Install through Homebrew on macOS:

  $ brew tap ValeLint/vale
  $ brew install vale
  

• Install via the Windows Installer package (.msi) on the releases page.

• Manually install on Windows, macOS, or 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

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.