How to lint your files with Vale

29. May 2020
Time4 min read


  • A code editor, like VS Code, Sublime, or Atom
  • The Vale-compatible implementation of the Microsoft Style Guide, which you can download here
  • The Vale CLI


  • You've read this post about the basics of Vale's configuration file.
  • You have some familiarity with the command line.

Step 1. Create project folder

In the terminal, create a new folder called vale-tutorial:

$ mkdir vale-tutorial

Step 2. Add project files

Change directories to the vale-tutorial folder:

$ cd vale-tutorial

Create a .vale.ini file in the vale-tutorial folder:

$ touch .vale.ini

Next, create a Markdown file called sample-file in the vale-tutorial folder:

$ touch

Finally, create a styles folder:

$ mkdir styles 

Your project structure now looks like this:

├── .vale.ini
└── styles  

Step 3. Add Microsoft styles to styles folder

Download and open the zip file containing the Vale-compatible implementation of the Microsoft Writing Style Guide. Then move the Microsoft folder to the styles folder. Now, your project structure looks like this:

├── .vale.ini
└── styles
    └── Microsoft  

Step 4. Edit the .vale.ini file in your code editor

Open your code editor now, and open the vale-tutorial folder. Click on the .vale.ini file to edit it. The first property to add is StylesPath.


In the .vale.ini file, set the StylesPath to styles. Remember: this is where you tell Vale where to look for any third-party styles.


Next, set MinAlertLevel to suggestions. If you remember, you can set this value to show errors, errors and warnings, or errors, warnings, and suggestions.


Set BasedOnStyles to Vale, Microsoft. Don't forget to add [*] so these styles are applied to all files.

Your .vale.ini file looks like this once you're done:

StylesPath = styles

MinAlertLevel = suggestions

[*] //don't forget the asterisk!
BasedOnStyles = Vale, Microsoft

Step 5. Add content to

Copy these three paragraphs and paste them into the file:

This is a sampl file that we can use to tst the Vale CLI. There are 2 things that you need to know about using it. Ergo There are plenty of cool things you can do with this linter...

In this tutorial, you will learn how to install Vale, a style linter this tool allows you to tst your doc file for style and grammar.

When a software developr tests their code, he may test the application's functionality or look for any security issues in their code. When technical writers test their documentation, we may check to assure that the links are not broken, the style is consistent, and that there are not grammar, spelling, or punctuation errors.

Step 6. Run the linter

From the terminal, run the command vale You'll see the errors, warnings, and suggestions Vale finds in the files, in addition to the number of errors, warnings, and suggestions:

6 errors, 4 warnings and 5 suggestions in 1 file.

The results

Vale.Spelling identified several typos:

1:11   error       Did you really mean 'sampl'?    Vale.Spelling
1:41   error       Did you really mean 'tst'?      Vale.Spelling  
4:94   error       Did you really mean 'tst'?      Vale.Spelling            
6:17   error       Did you really mean             Vale.Spelling            

Microsoft.We identified use of the first-person pronoun "we." Microsoft.Vocab caught several words that aren't on the word list:

 1:27   warning     Try to avoid using              Microsoft.We             
                    first-person plural like 'we'.   
 2:83   suggestion  Verify your use of 'cool' with  Microsoft.Vocab          
                    the A-Z word list.    
 6:200  suggestion  Verify your use of 'assure'     Microsoft.Vocab          
                    with the A-Z word list.                      

Notice that the Vale.Spelling has error level severity, while Microsoft.Vocab has suggestion level severity. This is how the rules are structured when you first download them, but you can change them, if you want. I'll talk about this in the next tutorial.

Key takeaways

  • Your .vale.ini file is 1) required and 2) controls Vale's behavior.
  • Your .vale.ini file should be in the root of your project.
  • Any third-party styles should be in your styles folder.
  • The .vale.ini file can be customized to show errors, errors and warnings, or errors, warnings, and suggestions.
  • To lint a file, use the command vale filename.


Now that you have Vale installed on your computer, you can start linting your own files to make sure they're error-free and consistent in style. This doesn't necessarily have to be documentation files, by the way; you can use Vale's default style to help with editing blog posts and emails.

Next, you'll learn how to customize a vale.ini file and modify style rules!

Have any trouble with the tutorial? Find any bugs? File a GitHub issue to let me know.