getting-started.md

Introduction to Vale rule development

The goal of this guide is to curate existing resources and provide pointers for anyone who is new to Vale rules. While it is not an in-depth tutorial, it aims to help you through installing and understanding Vale enough to create your first rules.

Overview

• Install the Vale CLI tool
• Develop a rule
  • Basics
• Regex
• Test rules
  • Test all rules
  • Test a specific rule
• Troubleshooting

Install the Vale CLI tool

The Vale CLI tool is the software that can apply Vale rules on any file in your local environment. This is how you can test your rule's behaviour while you develop it.

To install the Vale CLI tool, see the installation guide. To summarize:

• For Windows and MacOS, the easiest option is through the package managers.

• For Linux, the easiest option depends on whether or not you have Docker (run docker -v to check if Docker is installed).

  • If you do, then you just have to pull the container.
  • If you don't, the best option is to download the binaries from Vale's GitHub releases. Installing Docker just for Vale is not worth the hassle.

Develop a rule

A Vale rule is more than just a declaration or requirement - it's a definition of which lexical pattern(s) to search for and what to do when they are found.

Vale has its own key/value convention for defining these rule parameters via YAML syntax. This section will go over some basic examples to understand the general structure of a rule, and resources for developing more complex ones.

Basics

To develop a rule, you don't have to worry about setting up a particular environment or vale.ini configuration - all you need is an editor and this repository.

First, clone the repository if you haven't already.

git clone [email protected]:canonical/praecepta.git

Each rule is one file in the styles/Canonical directory. To create a new rule, add a .yml file and name it according to the convention you see in the other files: 000-Subject-brief-description.yml.

Important

Vale rules only work with the extension .yml. They will not work with .yaml.

Here is an example of a simple rule that prints a message whenever it finds the words "gonna" and "gotta":

extends: existence
message: "Do not use the contraction '%s'"
level: warning
tokens:
  - gonna
  - gotta

The extends key defines the type of search to perform. This is called an "extension point".

The extension value 'existence' checks whether certain words or characters exist. These are known as "tokens". If a match is found, Vale will throw a warning and return our message.

A similar extension point is 'substitution', but this one lets you define an alternative word to suggest to the user. For this extension point, you would use the swap key instead to map your tokens in the form of wrong: right, like in this example.

There are several other extensions, each with a particular set of keys to fine-tune the logic of the search and the rule's reaction to a match.

You can now use the documentation to find the extension point that best suits your rule, and see what parameters it requires.

Resources

• Rule examples:

  • github.com/testthedocs
  • github.com/errata-ai/vale

• Documentation:

  • In general, the two most useful pages from the official Vale documentation for rule development are the Styles and Scoping references.

Regex

Sometimes you'll need to search for specific patterns, expressions, or symbols instead of single words. This is where regular expressions come in.

For example, to search for the expression "Not only ...but also", you can define a token that will capture this regardless of what is written in between.

tokens:
  - 'not only.*?but also'

The single quotes indicate the beginning and end of the regex, and the .*? quantifier indicates that any characters can be in between when looking for matches.

Resources

• Interactive regex tutorial: Great for beginners
• Regex editor: Online tool that helps you compose and test your expressions. I like how it highlights capture groups in different colors.
• Before composing a complicated regex, remember to check for existing rules that might have done this already.

Test rules

Create a file in the root directory of the repository and fill it with text that you expect your rule to catch. It can be in any text format (.txt, .md, .rst...)

Besides the text file, the vale command needs a vale.ini config file. This file already exists in the root folder praecepta/. Vale will automatically find the vale.ini if you run the command in the same directory.

Test all rules

To apply all the rules inside styles/Canonical at the same time, run vale <file> in the root directory praecepta/.

For example:

vale test.md

Test a specific rule

To limit the test to a specific rule, you have to modify the vale.ini config file's style specification.

The default config specifies BasedOnStyles = Canonical, which will test all rules in that folder.

Comment that line out and add a line enabling your rule using the syntax <style>.<rule> = <YES | NO>

This edit would look similar to the snippet below:

; BasedOnStyles = Canonical
Canonical.000-My-Rule = YES

Once it is saved, you can run the command vale <file> in the root directory praecepta/.

For example:

vale test.md

in the root directory praecepta/.

Resources

• Configuration documentation - make your own vale.ini file(s) with specific configs for your tests
• Run vale -h to see optional parameters like output style and config path.

Troubleshooting

My rule isn't getting applied to the text

• Make sure the rule file uses the extension .yml instead of .yaml
• There might be a hidden syntax issue - consider using a local YAML linter or online tool to validate your rule.