In order to familiarize ourselves with the typical Vale workflow, we'll be referencing a sample repository that contains the required components of a Vale configuration.
If you're on Windows, we recommend using Windows Terminal instead of the default Command Prompt (which doesn't support all of Vale's features, as shown below):
- Windows Terminal
- Command Prompt
If you'd like to follow along locally, download or clone sample repository and copy the terminal session below:
The first component we're going to discuss is our
This where you'll store all of your Vale-related files (with the exception of
.vale.ini, discussed below).
In the example above, the
write-good top-level directories
are both styles. These are collections of individual writing
rules packaged together to enforce guidelines from a third-party organization
In practice, you'll typically come across two types of styles:
prose -> YAML: These styles take written guidelines (such as those from the Microsoft Writing Style Guide) and convert them into a collection of Vale-compatiable YAML files. The benefits of this process are that the style becomes both machine-readable and machine-enforceable.
write-good) and convert them into a collection of Vale-compatiable YAML files. The benefits of this process often include improved support for markup and easier installation and usage (Vale is a standalone, cross-platform binary—meaning you don't have to worry about configuring a programming language and its dependencies).
Vocab directory is a special directory design to
supplement your styles. Each of its child directories—in this case,
Marketing—contain two files:
These files allow you to control rule "exceptions" (such as what is considered a spelling error) without having to modify the style's source itself.
.vale.ini file is where you'll control the majority of Vale's behavior,
including what files to lint and how to lint them:
See the dedicated configuration section for more information.
In the sample repository,
README.md represents the content we want to lint.
And while you probably have a lot more content than a single Markdown file,
this example demonstrates one of Vale's most useful features: its support for
different markup languages.
In practice, this means that you can use Vale on "real-world" markup (that contains front matter, source code, tables, lists, etc.) and Vale will be able to both intelligently apply rules to and completely ignore certain sections of text.
At its core, Vale is designed to be used as a command-line tool. The available commands and options are discussed below.
Print the current configuration options (as JSON) to
(See Configuration for more information about the available options.)
Generate a template for the given extension point.
existence could be any of the available extension points.
--help option prints Vale's CLI usage information to
--glob option specifies the type of files Vale will search. It accepts
the standard GNU/Linux syntax. Additionally,
any pattern prefixed with an
! will be negated. For example,
This option takes precedence over any patterns defined in your configuration file.
--config option specifies the location of a configuration file. This
will take precedence over the default search process.
--output option specifies the format that Vale will use to report its
In addition to the 3 provided output styles, Vale also supports (as of
custom output styles powered by Go's
To use a custom format, pass the path to a template file through the
Template files have access to all of the sprig template functions, in addition to a few Vale-specific functions:
underline, which perform the text decoration used in Vale's default output style.
renderTable, which are utilities for consistent alignment.
Templates have access to the following data structure:
core.Alert has the same information as Vale's
Returns the given
STRING with an ANSI-formatted red foreground color.
Returns the given
STRING with an ANSI-formatted blue foreground color.
Returns the given
STRING with an ANSI-formatted yellow foreground color.
Returns the given
string with an ANSI-formatted underline.
Appends the given row to the given table (created with
Prints the table-formatted output to
The following example re-implements Vale's default output style using a template.
--ext option allows you to assign a format (e.g.,
.md) to text passed
stdin (which will default to
--no-wrap option disables word wrapping when using the
format. By default,
CLI output will be wrapped to fit your console.
--no-exit option instructs Vale to always return an exit code of
even if errors were found. This is useful if you don't want CI builds to fail
on Vale-related errors.
--sort option instructs Vale to sort its output by file path. For large
directories, this can have a noticeable impact on performance.
--ignore-syntax option will cause Vale to parse all files as plain
text. Note, though, that this doesn't change what files Vale will search.
This will often boost performance significantly, but only
--version option prints Vale's version.
--debug option instructs Vale to print debugging information to
--minAlertLevel option sets the minimum alert level to display. This
takes precedence over the value set in a configuration file.