Setting up the alex.js language linter in your project
11th Nov 2019
Updated on 8th Apr 2020
alex.js is an open-source language linter designed to catch polarizing writing in Markdown files and suggest helpful alternatives. Because its rules are rooted in retext-equality, alex is able to flag language that is ableist, condescending, gendered, homophobic, racist and anything else that's better left out of our documentation.
As a linter, alex can be used as a command-line tool, an IDE integration or configured directly into your project's workflow. For this tutorial, we'll focus on the latter: Your project's workflow.
Any line beginning with ❇️ is an example from the Unmock documentation setup.
- Install alex as a dependency
- Create and configure
- Set up
- Add linting script to
- Add linting script to your CI configuration (optional)
- alex && Unmock
- Special thanks
Run one of these commands in your terminal, depending on if you're using npm or yarn:
You should now be able to see alex as a dependency in your
.alexrc.js file in the root directory of your project:
In this file, you can specify three fields to configure how alex lints your project:
allow field, you can identify an array of rules (the words flagged as errors) that you always want alex to ignore.
❇️ While it's considered by alex as gendered language,
hostesses-hosts is allowed for Unmock because the concept of specifying network hosts is frequently referenced in our docs.
noBinary field is a boolean with the default set to
On the default setting, alex will flag the sentence
He must satisfy the function's preconditions as an error because
He is gendered language. But it sees gendered pairs, like
he or she as OK. So the sentence
He or she must satisfy the function's preconditions wouldn't be considered an error.
true will also flag those pairs.
❇️ We changed
true in our configuration file for Unmock because we want to eliminate all uses of gendered language.
Set with a number between 0-2, the
profanitySureness field uses cuss to determine how likely a word or phrase is profanity.
❇️ When linting the Unmock docs, we set
profanitySureness = 1 instead of the default
0 to catch the two highest levels.
The way we see it...
0: Contains words like
slope. These could be used as a profanity, but it's unlikely in the context of our technical documentation.
1: Much more explicit. While some words like
torture could be used appropriately in documentation - we'd prefer to find alternatives.
2: ... I can't write any of them here because I'll get in trouble. So they definitely don't belong in our docs.
This configuration can also be done in a standard
rc file or using YAML.
If you have specific files that you don't want alex to lint, you can create an
.alexignore file in the root directory of your project:
To prevent a file from being linted, identify the path in your newly created
❇️ We recommend adding a comment above the specified path. In the
.alexignore file for Unmock, for instance, we state why we ignore the Code of Conduct even though it includes many terms flagged by alex.
"scripts" section of your
package.json file, add a linting script with the
❇️ Because we're already linting Unmock with eslint, we named the script
lint-language to distinguish each process.
Depending on where your
package.json is located relative to the files you need linted, your script will vary.
For example, if the
package.json for the Unmock documentation was located at the root and we only wanted to lint the files in the
docs/ directory, the script would look like...
You can also add alex to your continuous integration workflow.
If you're using CircleCI, there are a few ways to accomplish this from your
.circleci/config.yml file. The following are two examples.
As its own job (example from React Native). That way, the language linting will be reported separately on PRs.
As a step in your test sequence (example from Unmock). The benefit being that it will execute faster than in its own job.
You can also configure alex to work with Travis or other CI tools.
Next move: Follow these steps to set up alex in all of our open source repos 🚀
This tutorial was inspired by a tweet from Rick Hanlon who recently integrated alex with the React Native documentation. He also reviewed this article before I hit publish! Thanks Ricky ✨
Don’t miss the next post!
Absolutely no spam. Unsubscribe anytime.