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.

If you'd like to follow along locally, download or clone the sample repository and copy the terminal session below:

$ cd vale-boilerplate
# Check your version of Vale:
$ vale -h
# Run Vale on the sample content:
$ vale README.md

 README.md
 13:20   warning  'extremely' is a weasel word!  write-good.Weasel
 15:120  warning  'However' is too wordy.        write-good.TooWordy
 27:6    error    'is' is repeated!              Vale.Repetition
 27:6    warning  'is' is repeated!              write-good.Illusions

✖ 1 errors, 3 warnings and 0 suggestions in 1 file.

`StylesPath`

The first component we're going to discuss is our StylesPath (the /styles directory):

$ tree styles
├───Microsoft
├───Vocab
│   ├───Blog
│   └───Marketing
└───write-good

This is 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-compatible 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's write-good) and convert them into a collection of Vale-compatible 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 designed 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:

.vale.ini

# Example Vale config file (`.vale.ini` or `_vale.ini`)

StylesPath = styles

Vocab = Blog

[*.md]
BasedOnStyles = Vale, write-good

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.

$ vale ls-config
{
  "BlockIgnores": {},
  "Checks": null,
  "Formats": {},
  "GBaseStyles": null,
  "GChecks": {},
  "IgnoredClasses": null,
  "IgnoredScopes": null,
  "MinAlertLevel": 0,
  "Path": "...",
  "Project": "",
  "RuleToLevel": {},
  "SBaseStyles": {
    "*.md": [
      "Vale"
    ]
  },
  "SChecks": {
    "*.md": {}
  },
  "SkippedScopes": null,
  "Stylesheets": {},
  "StylesPath": "...",
  "TokenIgnores": {},
  "WordTemplate": ""
}

(See Configuration for more information about the available options.)

`ls-metrics`

Print the given file's metrics.

$ vale ls-metrics cases/bench.md
{
  "blockquote": 1,
  "characters": 68001,
  "complex_words": 2000,
  "heading.h1": 2,
  "heading.h2": 13,
  "heading.h3": 27,
  "heading.h4": 13,
  "list": 16,
  "long_words": 3565,
  "paragraphs": 490,
  "polysyllabic_words": 2314,
  "pre": 168,
  "sentences": 841,
  "syllables": 23043,
  "words": 14303
}

`--help`

The --help option prints Vale's CLI usage information to stdout.

$ vale -h
...

`--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,

# Exclude `.txt` files
$ vale --glob='!*.txt' directory
...
# Only search `.md` and `.rst` files
$ vale --glob='*.{md,rst}' directory
...

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.

$ vale --config='some/file/path/.vale.ini'

`--output`

The --output option specifies the format that Vale will use to report its alerts.

# "line", "JSON", or "CLI" (the default)
$ vale --output=JSON directory

In addition to the three 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:

$ vale --output='path/to/my/template.tmpl' test.md

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, and renderTable, which are utilities for consistent alignment.

Templates have access to the following data structure:

type ProcessedFile struct {
    Alerts []core.Alert
    Path   string
}

type Data struct {
    Files       []ProcessedFile
    LintedTotal int
}

Where core.Alert has the same information as Vale's --output=JSON object.

Template functions

`red`

Syntax

red STRING

Returns the given STRING with an ANSI-formatted red foreground color.

`blue`

Syntax

blue STRING

Returns the given STRING with an ANSI-formatted blue foreground color.

`yellow`

Syntax

yellow STRING

Returns the given STRING with an ANSI-formatted yellow foreground color.

`underline`

Syntax

underline string

Returns the given string with an ANSI-formatted underline.

`newTable`

Syntax

newTable bool

Creates a new tablewriter struct. newTable accepts one boolean value representing SetAutoWrapText.

`addRow`

Syntax

addRow table []string

Appends the given row to the given table (created with newTable).

`renderTable`

Syntax

renderTable table

Prints the table-formatted output to stdout.

Template examples

The following example re-implements Vale's default output style using a template.

{{- /* Keep track of our various counts */ -}}

{{- $e := 0 -}}
{{- $w := 0 -}}
{{- $s := 0 -}}
{{- $f := 0 -}}

{{- /* Range over the linted files */ -}}

{{- range .Files}}
{{$table := newTable true}}

{{- $f = add1 $f -}}
{{- .Path | underline | indent 1 -}}

{{- /* Range over the file's alerts */ -}}

{{- range .Alerts -}}

{{- $error := "" -}}
{{- if eq .Severity "error" -}}
    {{- $error = .Severity | red -}}
    {{- $e = add1 $e  -}}
{{- else if eq .Severity "warning" -}}
    {{- $error = .Severity | yellow -}}
    {{- $w = add1 $w -}}
{{- else -}}
    {{- $error = .Severity | blue -}}
    {{- $s = add1 $s -}}
{{- end}}

{{- $loc := printf "%d:%d" .Line (index .Span 0) -}}
{{- $row := list $loc $error .Message .Check | toStrings -}}

{{- $table = addRow $table $row -}}
{{end -}}

{{- $table = renderTable $table -}}
{{end}}
{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}} and {{$s}} {{"suggestions" | blue}} in {{$f}} {{$f | int | plural "file" "files"}}.

`--ext`

The --ext option allows you to assign a format (e.g., .md) to text passed via stdin (which will default to .txt).

$ vale --ext='.md' '# this is a heading'

`--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.

$ vale --no-wrap directory

`--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.

$ vale --no-exit directory

`--sort`

The --sort option instructs Vale to sort its output by file path. For large directories, this can have a noticeable impact on performance.

$ vale --sort directory

`--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.

$ vale --ignore-syntax directory

`--version`

The --version option prints Vale's version.

$ vale --version
...

`--minAlertLevel`

The --minAlertLevel option sets the minimum alert level to display. This takes precedence over the value set in a configuration file.

$ vale --minAlertLevel LEVEL

Where LEVEL is suggestion, warning, or error.

StylesPath​

Styles​

Vocab​

.vale.ini​

README.md​

CLI reference​

ls-config​

ls-metrics​

--help​

--glob​

--config​

--output​

Template functions​

red​

blue​

yellow​

underline​

newTable​

addRow​

renderTable​

Template examples​

--ext​

--no-wrap​

--no-exit​

--sort​

--ignore-syntax​

--version​

--minAlertLevel​

`StylesPath`

Styles

Vocab

`.vale.ini`

`README.md`

CLI reference

`ls-config`

`ls-metrics`

`--help`

`--glob`

`--config`

`--output`

Template functions

`red`

`blue`

`yellow`

`underline`

`newTable`

`addRow`

`renderTable`

Template examples

`--ext`

`--no-wrap`

`--no-exit`

`--sort`

`--ignore-syntax`

`--version`

`--minAlertLevel`