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

--

--

--

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

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Microservice chassis

An Engineering Day That Works

Come work for Ars and write about cool tech

Building a Token Refresh service for the Fitbit API with Azure Functions and C#

Android Developer Beginner. FAQ #2 — gravity vs layout_gravity

5 Popular Linux Distributions for Developers

Executor Engine: Performance Optimization — Apache ShardingSphere 5.1.0

Supabase: Setting up Authentication

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nwokocha Wisdom Maduabuchi

Nwokocha Wisdom Maduabuchi

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

More from Medium

Things to Know When Hiring a Technical Writer

How sales engineers can help you achieve your goals

7 Best Tips for Web Developers When Coding for Ecommerce Websites

6 Websites You Need To Use In 2022 (Design, Development, Learning, E-Commerce and More!)