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

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.

Example:

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

Requirements

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 sample-file.md

Finally, create a styles directory:

$ mkdir styles

Your project structure now looks like this:

vale-example
├── .vale.ini
├── sample-file.md
└── 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-tutorial
├── .vale.ini
├── sample-file.md
└── 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.

StylesPath

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

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

MinAlertLevel

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

BasedOnStyles

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 sample.md

Copy these example post and paste them into the sample.md 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 sample.md 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 
                    ellipsis.                                          
 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: https://docs.github.com/en/actions 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.
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]

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

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

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

      env:
        GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

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

Conclusion

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
Twitter: https://twitter.com/Joklinztech
LinkedIn: https://www.linkedin.com/in/wisdom-nwokocha-76212a77/
Youtube channel: https://www.youtube.com/channel/UCGh4vu4cVz72cvgFG2QHnWQ