Automate Style Checks

Vale is a tool that brings code-like linting to text. You can run the tool on a file and it shows validation errors based on designated Style Guides.

This article describes how to install and configure Vale locally, then configure the IntelliJ IDE (with the AsciiDoc plugin) to use Vale in a Mac environment.

Note: Grazie Professional is IntelliJ's plugin that supports a growing subset of Vale's functionality. The reason this author chose to use Vale instead of Grazie is because our team uses several IDEs.

Install, configure, and test Vale locally

Prerequisite: You must have AsciiDoctor installed.

Install Vale

• Run brew install vale.

Configure Vale

1. Create a directory at the root of your system named styles.
2. Go to?https://github.com/errata-ai/packages.
3. Scroll to the?Available styles?section. Click the style to include, like?Google.
4. Click to download the latest release, then click the latest?.zip?file.
5. Unzip the folder in the styles folder.
6. Create?.vale.ini?at the root of your system with the following contents:

Note:?Update BasedOnStyles to include the styles that you downloaded in step 1.

# Core setting
StylesPath = styles


# The                  (suggestion, warning, or error).
#
# CI builds will only fail on error-level alerts.


MinAlertLevel = suggestion
# MinAlertLevel = warning


# Define the exceptions to use in *all* `BasedOnStyles`.
Vocab = Docs


[*.md]
BasedOnStyles = Google, Vale, proselint
TokenIgnores = (\[.*?\].*?\[\/\w+\])? ?# ignore shortcodes


[*.adoc]
BasedOnStyles = Google, Vale, proselint
TokenIgnores = (\[.*?\].*?\[\/\w+\])? ?# ignore shortcodess        

Test Vale

To test Vale in Terminal, go to a directory with an AsciiDoctor (.adoc) file and run:

vale <filename>        

If you get results similar to the following, your configuration is correct:

Configure IntelliJ

1. Install the Awesome Console.

2. Go to IntelliJ IDEA > Preferences > Tools > External Tools.

3. Add Vale and enter the following for Arguments:

--config /Users/<your user directory>/.vale.ini --output line --sort --relative $FilePathRelativeToProjectRoot$        

4. Enter the following for Working directory:

$ProjectFileDir$         

5. Click OK.

6. Click Apply and OK.

Define a keyboard shortcut

1. In Preferences, go to Appearances & Behavior > Keymap.
2. Go to Tools > External Tools > Vale.
3. Right-click Vale.

4. Type the shortcut on your keyboard and click OK.

Define an icon

1. In Preferences, go to Menus and Toolbars.
2. Select a toolbar such as Main Toolbar > Toolbar Run Actions.
3. Click + to add an action.
4. Go to External Tools > External Tools > Vale and click OK.
5. Click Apply and OK. The shortcut is in the toolbar specified.

Open any file and use your keyboard shortcut, toolbar icon, or go to Tools > External Tools > Vale. The results are shown in the Run window.

Create custom styles

Although you can modify the existing styles, if you pull an existing Style Guide to get the latest content, your changes might be overwritten. Therefore, I recommend that you create custom styles if needed.

1. Create a folder, such as MyStyles.
2. Add the folder name to the BasedOnStyles = Vale, Microsoft, proselint, MyStyles line in vim .vale.ini.
3. Add the content for your custom styles. For example, if your organization has words that are not accepted such as please or via. These will show in the results as follows: