How to automate linting your documentation using Vale and Github actions.

Nwokocha Wisdom Maduabuchi
5 min readMay 29, 2022

Vale is a syntax-aware linter and a command-line tool that brings code-like linting to prose, and you can also implement both the Microsoft Writing Style Guide and the Google Developer Documentation Style Guide with it. It’s open-source, fast, and highly customizable. It supports Markdown, AsciiDoc, reStructuredText, HTML, and more.

Linting is the process of reviewing your source code or documentation for programmatic and stylistic problems using an automated system. A lint tool is used to accomplish this (otherwise known as linter). A basic static code analyzer is a lint tool.

What does it mean to automate documentation? It means you are using a continuous integration and continuous deployment (CI/CD) pipeline to check for errors and deploy changes and also use a tool like Vale to enforce a style guide and correct grammatical mistakes.


StylesPath = a/path/to/your/styles
MinAlertLevel = suggestion
BasedOnStyles = Vale


  • 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 have some familiarity with the command line.
  • You’ve read this post about the basics of Vale’s configuration file.

Make sure “.vale.ini” file and styles folder are on the root folder of your project, else you will face errors like ( Error: The process ‘/github/home/vale’ failed with exit code 2 ).

Create project directory

In the terminal, create a new directory called vale-example:

mkdir vale-example

Add vale files

Change the directory to the vale-example directory:

$ cd vale-example

Create a .vale.ini file in the vale-example directory:

$ touch .vale.ini

Next, create a Markdown file called sample in the vale-example directory:

$ touch

Finally, create a styles directory:

$ mkdir styles

Your project structure now looks like this:

├── .vale.ini
└── styles

Add Microsoft styles to the styles directory

Download and unzip the file containing the Microsoft Writing Style Guide. Then move the Microsoft directory to the styles directory.
Your project structure should look like the below example.

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

Modify the .vale.ini file in your code editor

Open the vale-tutorial directory and the .vale.ini. file, add StylesPath as the first property.


In the .vale.ini file, set the StylesPath to styles.

This tells Vale where to look for any third-party styles.


Next, set MinAlertLevel to suggestions, you can also set this value to show errors, warnings, and suggestions.


Set BasedOnStyles to Vale, Microsoft.

Note: add [*] in the .vale.inifile so the styles are applied to all files.

Your .vale.ini should look like the below example.

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

Add content to

Copy these example post and paste them into the file:

This is a sample txt file for testing the Vale CLI. There are two things you should knw before utilizing it. As a rsult, you can perform a lot of creative things with this linter…

You will learn how to install Vale, a style linter, in this article. This tool allows you to tst your doc file for style and grammar.

A software developer may tst the application’s functioning or search for any security concerns in their code when testing their code. Wen technical writers test their documentation, they may look for broken lnks, inconsistent style, and grammatical, spelling, and punctuation mistakes.

Run the linter

Run the command vale from your terminal to let Vale find errors, warnings, and suggestions in the files. This will help you build better documentation.

1:11   suggestion  Verify your use of 'sample'     Microsoft.Vocab    
with the A-Z word list.
1:18 error Did you really mean 'txt'? Vale.Spelling
1:85 error Did you really mean 'knw'? Vale.Spelling
1:115 error Did you really mean 'rsult'? Vale.Spelling
1:179 warning In general, don't use an Microsoft.Ellipses
3:80 suggestion Verify your use of 'allows' Microsoft.Vocab
with the A-Z word list.
3:94 error Did you really mean 'tst'? Vale.Spelling
5:26 error Did you really mean 'tst'? Vale.Spelling
5:208 error Did you really mean 'lnks'? Vale.Spelling

Important Details

  • Your .vale.ini file should be in the root of your project.
  • Any third-party styles should be in your styles folder.
  • To lint, a file, use the command vale filename.

Automate vale using Github actions

In this article, I will assume you know how to set up the Github action workflow if you don't visit this link: to learn more about it.

Once you’ve created a workflows directory, you can give it any name that fits the project, but in this tutorial I will name this workflow vale.yml.

Now, open vale.yml in your favorite text editor.

nano vale.yml

Copy and paste the following into vale.yml

name: Editorial Review

# Controls when the action will run.
# Triggers the workflow on push or pull request events but only for the main branch
branches: [ main ]

# Allows you to run this workflow manually from the Actions tab

runs-on: ubuntu-latest
- name: Checkout
uses: actions/checkout@master

- name: Vale
uses: errata-ai/vale-action@reviewdog
files: vale-tutorial/


Once you’ve finished making changes, save the file, commit it to Git, and push your changes to GitHub, go to the Actions tab and click it.

You will see your workflow on the left side named Editorial Review.

Click on “Update vale” to get a full report.

Full example on Github link


You can start linting your own files now that Vale is installed on your computer to ensure they’re error-free and consistent in style.
To deliver quality documentation, you would need an extra eye to help you check for grammatical mistakes and more checks related to writing, also you can utilize Vale’s default style to assist you in editing blog posts and emails.

Let’s connect on
Youtube channel:



Nwokocha Wisdom Maduabuchi

A software engineer with considerable experience in mobile development, native Android, and IOS development(Xcode), flutter dev, technical writing and community