How to Use Vale With MDX
Created: Dec 14, 2023 – Last Updated: Dec 14, 2023
Tags: CLI, MDXDigital Garden
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:
- How to install and use Vale as an npm package
- How to configure Vale’s
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.
@vvago/valeas a devDependency:
Add the following two entries to your
<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
Try running the following script in your terminal:
You should see a similar output to this:
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
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).
.vale.ini and add the following:
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
TokenIgnores inside the configuration options (opens in a new tab) to exclude these. An example config could look like this: