Docs
Topics
Styles

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.

yaml
# 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,

console
$ 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

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

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".
CLI Scopes