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

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.

Create project directory

mkdir vale-example

Add vale files

$ cd vale-example
$ touch .vale.ini
$ touch sample-file.md
$ mkdir styles
vale-example
├── .vale.ini
├── sample-file.md
└── styles

Add Microsoft styles to the styles directory

vale-tutorial
├── .vale.ini
├── sample-file.md
└── styles
└── Microsoft

Modify the .vale.ini file in your code editor

StylesPath

MinAlertLevel

BasedOnStyles

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

Add content to sample.md

Run the linter

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

nano 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}}

Conclusion

--

--

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