How to automate linting your documentation using Vale and Github actions.
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
Add vale files
Change the directory to the
$ cd vale-example
.vale.ini file in the
$ touch .vale.ini
Next, create a Markdown file called
sample in the
$ touch sample-file.md
Finally, create a
$ mkdir styles
Your project structure now looks like this:
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
Your project structure should look like the below example.
Modify the .vale.ini file in your code editor
vale-tutorial directory and the
.vale.ini. file, add
StylesPath as the first property.
.vale.ini file, set the
This tells Vale where to look for any third-party styles.
suggestions, you can also set this value to show errors, warnings, and suggestions.
Note: add [*] in the
.vale.inifile so the styles are applied to all files.
.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
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
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
.vale.inifile should be in the root of your project.
- Any third-party styles should be in your
- To lint, a file, use the command
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 in your favorite text editor.
Copy and paste the following into
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
- name: Checkout
- name: Vale
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
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: https://www.youtube.com/channel/UCGh4vu4cVz72cvgFG2QHnWQ