Setting up the alex.js language linter in your project

CS
Carolyn Stransky

Software Engineer

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.

⚠️ Prerequisites:#

Any line beginning with ❇️ is an example from the Unmock documentation setup.

Table of Contents#

Install alex as a dependency#

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 package.json file.

Create and configure .alexrc.js#

To configure alex using JavaScript, create an .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, noBinary and profanitySureness.

allow#

With the allow field, you can identify an array of rules (the words flagged as errors) that you always want alex to ignore.

🔗 Full list of rules used by alex

❇️ 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#

The noBinary field is a boolean with the default set to false.

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.

Switching noBinary to true will also flag those pairs.

❇️ We changed noBinary to true in our configuration file for Unmock because we want to eliminate all uses of gendered language.

profanitySureness#

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...

unlikely - 0: Contains words like execute, failed, pros or slope. These could be used as a profanity, but it's unlikely in the context of our technical documentation.

maybe - 1: Much more explicit. While some words like addicted, abuse or torture could be used appropriately in documentation - we'd prefer to find alternatives.

likely - 2: ... I can't write any of them here because I'll get in trouble. So they definitely don't belong in our docs.

🔗 Full list of English words flagged by cuss

Configuring alex without JavaScript#

This configuration can also be done in a standard rc file or using YAML.

🔗 Configuration - alex documentation

Set up .alexignore (optional)#

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 .alexignore:

❇️ 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.

🔗 Ignoring files - alex documentation

Add linting script to package.json#

In the "scripts" section of your package.json file, add a linting script with the alex command.

❇️ 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...

🔗 Workflow - alex documentation

Add linting script to your CI configuration (optional)#

You can also add alex to your continuous integration workflow.

CircleCI#

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.

Other CI tools#

You can also configure alex to work with Travis or other CI tools.

🔗 Workflow - alex documentation

alex && Unmock#

Thanks to Abdelrahman Ashraf (@theashraf), we now have alex linting our entire documentation website and all of the pre-existing issues fixed for Unmock.

Next move: Follow these steps to set up alex in all of our open source repos 🚀

Special thanks#

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 ✨

Newer postOlder post

Don’t miss the next post!

Absolutely no spam. Unsubscribe anytime.

Company

About usContactPricingT&C