How to Use Vale With MDX

Vale (opens in a new tab) is an open-source command-line tool to lint your prose. It’s fast, extensible, and syntax-aware. It supports linting Markdown but at the time of writing this post it doesn’t natively lint MDX.

In this short article I want to give you two tips:

1. How to install and use Vale as an npm package
2. How to configure Vale’s .vale.ini

I recommend reading through Vale’s documentation (opens in a new tab) if you need instructions on how to set it up or how to add styles ⸺ because I won’t touch on these topics here.

#How to install & use Vale as an npm package

If you’re using MDX you’re most likely working in a Node.js environment and as such use npm. You can install (opens in a new tab) vale as a binary for your platform. However, by going that route you’ll require every person who wants to run Vale to go through the same installation steps. Instead, install @vvago/vale (opens in a new tab) as a dependency and use it instead.

1. Install @vvago/vale as a devDependency:

   shell

   CopyCopy code to clipboard

   npm install -D @vvago/vale

2. Add the following two entries to your package.json scripts:

   package.json

   json

   Copypackage.json: Copy code to clipboard

   {
     "scripts": {
       "vale": "./node_modules/@vvago/vale/bin/vale",
       "lint": "npm run vale -- <path-to-your-files>"
     }
   }

   Replace <path-to-your-files> with a path, e.g. if your docs live in docs/ then use that. If you want to lint everything, use ..

3. Try running the following script in your terminal:

   shell

   CopyCopy code to clipboard

   npm run vale -- -h

   You should see a similar output to this:

   shell

   CopyCopy code to clipboard

   ➜ npm run vale -- -h
   
   > vale-test@1.0.0 vale
   > ./node_modules/@vvago/vale/bin/vale -h
   
   vale - A command-line linter for prose.
   
   Usage:	vale [options] [input...]
     vale myfile.md myfile1.md mydir1
     vale --output=JSON [input...]
   
   Vale is a syntax-aware linter for prose built with speed and extensibility in
   mind. It supports Markdown, AsciiDoc, reStructuredText, HTML, and more.

Great, you can run Vale now. Follow Vale’s documentation (opens in a new tab) to setup your .vale.ini configuration file and in the next step you’ll learn how to use it with MDX.

#How to configure Vale’s .vale.ini

MDX isn’t one of Vale’s supported formats so you’ll need to associate an unknown format (in this case MDX) with a known format (Markdown).

Open your .vale.ini and add the following:

# Treat MDX as Markdown
[formats]
mdx = md

This gives you some baseline functionality with Vale. But since MDX enables you to use JSX in Markdown, you need to tell Vale to ignore those parts as it can’t parse them correctly.

You should explore using IgnoredScopes, SkippedScopes, BlockIgnores, and TokenIgnores inside the configuration options (opens in a new tab) to exclude these. An example config could look like this:

IgnoredScopes = code, tt, img, url, a
SkippedScopes = script, style, pre, figure, code
# Ignore code surrounded by backticks or plus sign, parameters defaults, URLs, and angle brackets.
TokenIgnores = (<\/?[A-Z].+>), (\x60[^\n\x60]+\x60), ([^\n]+=[^\n]*), (\+[^\n]+\+), (http[^\n]+\[)