Edit Markdown documents with Vale

Vale is an open tool for creating and enforcing custom style, grammar, and spelling rules for Markup documents. It is available as a cross-platform command line executable with Markdown, HTML, reStructuredText, AsciiDoc, and DITA support. Please see What is (and isn’t) Vale? for more information on exactly what Vale can do.

Purpose

This guide explains how to install, configure, and use Vale to enforce LinkORB’s content style guide. It discusses how to:

Install and configure Vale

How you install Vale depends on your current platform.

Dev containers

Install and configure the latest version of Vale in a development (dev) container by adding the following directive to the dev container’s Dockerfile.

Vale is automatically installed and configured when running the Engineering site’s repository in a devcontainer.

RUN wget -O vale-tags https://github.com/errata-ai/vale/tags && \
    VALE_LATEST_VERSION=$(grep -E '>(v[0-9]+.)+' vale-tags | head -n 1 | awk -F '>|<' '{print $5}') && \
    VALE_DOWNLOAD_URL=$(echo "https://github.com/errata-ai/vale/releases/download/$VALE_LATEST_VERSION/vale_${VALE_LATEST_VERSION:1}_Linux_64-bit.tar.gz") && \
    wget -L -O vale.tar.gz $VALE_DOWNLOAD_URL && \
    tar -xvzf vale.tar.gz -C bin && \
    rm vale-tags vale.tar.gz

ENV PATH="/app/bin:$PATH"

The RUN command above assumes there is a bin/ folder at the root of the working directory. Please add mkdir bin &&\ between the second wget and the tar commands in the above code if the working directory does not contain a bin/ at the time of running the above command.

The ENV command assumes /app/ is the container’s or image’s working directory, so it adds /app/bin to the PATH environment variable to make Vale globally accessible. Please replace /app/bin with the folder where you’ve stored Vale if it is saved to a different folder.

Note that tar and wget must be installed as dependencies in order for this to work.

Linux

The easiest way to install Vale on Linux is to run the following Snapcraft command in the terminal.

snap install --edge vale

However, Linux package managers like Snapcraft are infamous for installing older versions of a package. To install the latest version, run the following command at the root of your project to install and configure vale.

wget -O vale-tags https://github.com/errata-ai/vale/tags && \
    VALE_LATEST_VERSION=$(grep -E '>(v[0-9]+.)+' vale-tags | head -n 1 | awk -F '>|<' '{print $5}') && \
    VALE_DOWNLOAD_URL=$(echo "https://github.com/errata-ai/vale/releases/download/$VALE_LATEST_VERSION/vale_${VALE_LATEST_VERSION:1}_Linux_64-bit.tar.gz") && \
    wget -L -O vale.tar.gz $VALE_DOWNLOAD_URL && \
    tar -xvzf vale.tar.gz -C bin && \
    export PATH="$(pwd)/bin:$PATH" && \
    rm vale-tags vale.tar.gz

If you prefer to install Vale as a globally accessible executable, run the following command from the root of the project:

sudo mv $(pwd)/bin/vale /usr/local/bin/vale

Windows

Install and configure Vale on Windows as follows:

Visit https://github.com/errata-ai/vale/releases.
Download the vale_<version>_Windows_64-bit.zip file from the Assets section of the latest release.
Extract vale.exe file from the downloaded archive and save it into the bin/ folder at the root of your project. Alternatively, save the extracted Vale executable to a different folder outside the project folder if you prefer to use a single Vale executable in multiple projects.
Click the Start menu icon and type Command prompt.
Right click Command prompt and select Run as administrator.
Navigate to the bin/ folder of the project (or the folder where you’ve saved the Vale executable) in the terminal.
Run the following command to add the folder to the systme’s PATH environment variable.

setx PATH "C:\path\to\vale\folder;%PATH%"

macOS

Install Vale on macOS using Homebrew with the following command:

brew install vale

Proofread and edit documents using Vale

Run vale path/to/folder/*.md to check all *.md files in a given folder for spelling, grammar, and style violations. For example, the following command checks *.md files in the /src/pages/blog/ folder for grammar, spelling, and styling/syntax problems:

vale src/pages/blog/*.md

To proofread a single document, run vale path/to/file instead. For example, the following command instructs Vale to check only the vale-tips.md file in the src/pages/blog/ folder.

vale src/pages/blog/vale-tips.md

Vale sets its alert level to “suggestion” by default. This means Vale will report errors and warnings for each violation, then offer suggestions to fix the issues. If you prefer to have Vale report only errors, run Vale with the --minAlertLevel flag set to errors as shown below:

vale --minAlertLevel=errors /path/to/file(s)

Note that setting --minAlertLevel to warning instructs Vale to alert a writer to errors and warnings.

Vale does not currently understand .mdx files and treats it as regular .md files. This works well mostly, but it causes unintended warnings on JSX or frontmatter blocks. This requires some regular expressions to filter out.

To better understand the Vale output, refer to the Vale Package Hub docs and the /vale/styles/ folder from the root directory of the astro-engineering repository.

Configure a custom style guide

The main configuration file is .vale.ini in the root of the project. It contains a list of styles to use, and some configuration options.

The styles and vocabularies are located in the vale/styles directory.

Files commonly edited are accept.txt and reject.txt in the /vale/styles/Vocab/LinkORB folder. These files contain words, phrases, and regular expressions. The accept.txt file is effectively an allowlist for what Vale would otherwise consider a spelling error. Inversely, the reject.txt file contains content that Vale would otherwise accept, but we want to warn against it explicitly. For more information on these files, see the related Vale docs.

Please see Vale configuration, vocabularies, and styles for comprehensive guidance on how to create and customize a style guide.

For examples of Vale style guides, please see the following resources:

Edit Markdown documents with Vale in [#technical-documentation]