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.
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.ini
file 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