Usage
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.
Heads up!
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:
StylesPath
The first component we're going to discuss is our StylesPath
(the /styles
directory):
This where you'll store all of your Vale-related files (with the exception of
.vale.ini
, discussed below).
Styles
In the example above, the Microsoft
and 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
or tool.
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.code -> YAML
: These styles take guidelines enforced by a language-dependent tool (such as JavaScript'swrite-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).
The dedicated styles section explains how you can create your own custom style. You can also browse our collection of pre-made, open-source styles.
Vocab
The Vocab
directory is a special directory design to
supplement your styles. Each of its child directories—in this case,
Blog
and Marketing
—contain two files: accept.txt
and reject.txt
.
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
The .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.
README.md
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.
CLI reference
At its core, Vale is designed to be used as a command-line tool. The available commands and options are discussed below.
ls-config
Print the current configuration options (as JSON) to stdout
.
(See Configuration for more information about the available options.)
new-rule
Generate a template for the given extension point.
Where existence
could be any of the available extension points.
--help
The --help
option prints Vale's CLI usage information to stdout
.
--glob
The --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
The --config
option specifies the location of a configuration file. This
will take precedence over the default search process.
--output
The --output
option specifies the format that Vale will use to report its
alerts.
In addition to the 3 provided output styles, Vale also supports (as of v2.6
)
custom output styles powered by Go's
text/template
package.
To use a custom format, pass the path to a template file through the --output
option:
Template files have access to all of the sprig template functions, in addition to a few Vale-specific functions:
red
,blue
,yellow
, &underline
, which perform the text decoration used in Vale's default output style.newTable
,addRow
, andrenderTable
, which are utilities for consistent alignment.
Templates have access to the following data structure:
Where core.Alert
has the same information as Vale's --output=JSON
object.
Template functions
red
Syntax
Returns the given STRING
with an ANSI-formatted red foreground color.
blue
Syntax
Returns the given STRING
with an ANSI-formatted blue foreground color.
yellow
Syntax
Returns the given STRING
with an ANSI-formatted yellow foreground color.
underline
Syntax
Returns the given string
with an ANSI-formatted underline.
newTable
Syntax
Creates a new tablewriter
struct. newTable
accepts one boolean value representing
SetAutoWrapText
.
addRow
Syntax
Appends the given row to the given table (created with newTable
).
renderTable
Syntax
Prints the table-formatted output to stdout
.
Template examples
The following example re-implements Vale's default output style using a template.
--ext
The --ext
option allows you to assign a format (e.g., .md
) to text passed
via stdin
(which will default to .txt
).
--no-wrap
The --no-wrap
option disables word wrapping when using the CLI
output
format. By default, CLI
output will be wrapped to fit your console.
--no-exit
The --no-exit
option instructs Vale to always return an exit code of 0
,
even if errors were found. This is useful if you don't want CI builds to fail
on Vale-related errors.
--sort
The --sort
option instructs Vale to sort its output by file path. For large
directories, this can have a noticeable impact on performance.
--ignore-syntax
The --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 text
-scoped rules
will work.
--version
The --version
option prints Vale's version.
--debug
The --debug
option instructs Vale to print debugging information to stdout
.
--minAlertLevel
The --minAlertLevel
option sets the minimum alert level to display. This
takes precedence over the value set in a configuration file.
Where LEVEL
is suggestion
, warning
, or error
.