As I mentioned in the first part of the series, in the second part, you'll learn how to configure the Vale CLI for your documentation needs. Before you dive into the tutorial, you need to learn a thing or two about the file that makes linting with Vale possible: the
What is the .vale.ini file?
.vale.ini file is a configuration file that tells Vale what files to lint, or check, what styles to conform to, and what rules to ignore. Essentially, it controls everything Vale does for you.
Q: Why is there a period in front of the filename?
A: Any filename that begins with a period is called a hidden file. Hidden files are usually tucked away for a good reason: they're files that you probably shouldn't touch unless you know what you're doing.
Q: What does
.iniextension indicates that this is an initialization file.
Here's a basic, bare-bones
StylesPath = styles MinAlertLevel = suggestion [*] the asterisk means "apply these styles to all files" and is required. BasedOnStyles = Vale
It has several properties:
StylesPath tells Vale where to look for third-party styles. In this example, all third-party styles are in the
When you run the Vale CLI, it displays the number of errors, warnings, and suggestions found in the file. Errors are highest in severity; suggestions are lowest:
2 errors, 3 warnings and 3 suggestions in 1 file.
If you want, you can configure Vale to show errors only, errors and warnings, or show errors, warnings, and suggestions. For example, if you set
error, it only shows errors found in the file:
2 errors, 0 warnings and 0 suggestions in 1 file.
If you set
warning, it only shows errors and warnings:
2 errors, 3 warnings and 0 suggestions in 1 file.
If you set
suggestions, it shows errors, warnings, and suggestions:
2 errors, 0 warnings and 3 suggestions in 1 file.
This is the fun part.
One of the great things about Vale is that it allows you to use third-party styles with it. For example, if your company follows Microsoft's style guide, you can download a zip file containing an implementation of the Microsoft Writing Style Guide that you can use with Vale.
If you don't use a third-party style guide, you can always use the default style, which is
If you want Vale to implement more than one style, separate them with a comma, as shown below:
BasedOnStyles = Vale, Microsoft
Now, Vale uses its default style and Microsoft's style rules when linting your files.
StylesPathtells Vale where to look for third-party styles.
- You can configure Vale to show errors, errors and warnings, or errors, warnings, and suggestions.
- You can use Vale's default style to lint your files, or you can use a third-party style.
- At minimum, your
.vale.inifile must include
Now you know what a
.vale.ini file is and its basic components. Next, you'll create a
.vale.ini file and run the CLI to lint a sample Markdown file, using Vale's and Microsoft's style rules. To get started with the tutorial, click here.