Styles

Learn about the primary component of Vale's configuration system.

Vale has a powerful extension system that doesn’t require knowledge of any programming language. Instead, it uses collections of individual YAML files (or “rules”) to enforce particular writing constructs.

# An example rule from the "Microsoft" style.
extends: existence
message: "Don't use end punctuation in headings."
link: https://docs.microsoft.com/en-us/style-guide/punctuation/periods
nonword: true
level: warning
scope: heading
action:
  name: edit
  params:
    - remove
    - '.?!'
tokens:
  - '[a-z0-9][.?!](?:\s|$)'

These collections are referred to as styles and are organized in a nested folder structure at a user-specified location. For example,

$ tree styles
styles/
├── base/
│   ├── ComplexWords.yml
│   ├── SentenceLength.yml
│   ...
├── blog/
│   ├── TechTerms.yml
│   ...
└── docs/
    ├── Branding.yml

where base, blog, and docs are your styles that each contain certain rules.

Rules

Heads up!

Make sure your rule files end in extension .yml. Do not end them in .yaml, as Vale will not detect them.

The building blocks of styles are called rules (YAML files ending in .yml), which utilize checks to perform specific tasks.

The structure of a rule consists header followed by check-specific arguments. Every rule supports the following header fields:

Name	Required	Default	Description
extends	Yes	N/A	The name of the check to extend in the particular rule. See Rules for more information. <br>extends: existence<br>
message	Yes	N/A	The message to display when the rule is triggered. Each extension point has different formatting options. <br>message: "Don't use '%s' headings."<br>
level	No	suggestion	The severity of the rule. The available options are suggestion, warning, and error. <br>level: warning<br>
scope	No	text	The scope of the rule. See Scopes for more information. <br>scope: heading<br>
link	No	N/A	A URL to associate with the rule. This is useful for providing more information about the rule. <br>link: https://example.com<br>
limit	No	N/A	The maximum number of times the rule can be triggered in a single file. <br>limit: 3<br>
vocab	No	true	If set to false, any active vocabularies will be disabled for the rule. <br>vocab: false<br>

Checks

Each rule extends a specific check, which is a built-in function that performs a particular task. For example, the existence check ensures that a given pattern is present in the content.

Name	Description
existence	Check for the presence of a specific regex pattern.
substitution	Replace a regex pattern with a specific string.
occurrence	Ensure the presence of a regex pattern a specific number of times.
repetition	Avoid repeating a regex pattern a specific number of times.
consistency	Ensure that a regex pattern is used consistently.
conditional	Check for the presence of a regex pattern based on a condition.
capitalization	Ensure that a regex pattern is capitalized in a specific way.
metric	Check the readability (or other metrics) of your content using custom forumulas.
spelling	Spell check using Hunspell-compatible dictionaries.
sequence	Ensure that a regex pattern is used in a specific order. Supports part-of-speech tagging.
script	Run a custom Tengo script to check your content.

Regex

Many rules will require the use of regular expressions to match specific patterns in your content. Vale uses a superset of Go’s regexp/syntax package to provide a powerful and flexible regex engine.

In addition to the standard Go regex syntax, Vale also supports positive lookahead ((?=re)), negative lookahead ((?!re)), positive lookbehind ((?<=re)), and negative lookbehind ((?<!re)).

See the Regex guide for more information.

Vale

Vale comes with a single built-in style named Vale that implements a few rules, as described in the table below.

Name	Description
Vale.Spelling	Checks for spelling errors in your content. Consumes any Hunspell-compatible dictionaries stored in <StylesPath>/config/dictionaries.
Vale.Terms	Enforces the current project's accepted Vocabulary terms.
Vale.Avoid	Enforces the current project's rejected Vocabulary terms.
Vale.Repetition	Flags repeated words such as "the the" or "and and".