📝 alex — Catch insensitive, inconsiderate writing.

Whether your own or someone else’s writing, alex helps you find gender favoring, polarizing, race related, religion inconsiderate, or other unequal phrasing in text.

For example, when

We’ve confirmed his identity

their

his

Give alex a spin on the Online demo ».

Why

• [x] Helps to get better at considerate writing
• [x] Catches many possible offences
• [x] Suggests helpful alternatives
• [x] Reads plain text, HTML, MDX, or markdown as input
• [x] Stylish

Install

Using npm (with Node.js):

$ npm install alex --global

Using yarn:

$ yarn global add alex

Or you can follow this step-by-step tutorial: Setting up alex in your project

Contents

• Checks
• Integrations
• Ignoring files

  • .alexignore

• Control
• Configuration
• CLI
• API

  • markdown(value, config)

  • mdx(value, config)

  • html(value, config)

  • text(value, config)

• Workflow
• FAQ
  • This is stupid!
  • alex didn’t check “X”!
  • Why is this named alex?
• Further reading
• Contribute
• Origin story
• Acknowledgments
• License

Checks

alex checks things such as:

• Gendered work-titles (if you write

  garbageman

  alex suggests

  garbage
  collector

  ; if you write

  landlord

  alex suggests

  proprietor

  )
• Gendered proverbs (if you write

  like a man

  alex suggests

  bravely

  ; if you write

  ladylike

  alex suggests

  courteous

  )
• Ableist language (if you write

  learning disabled

  alex suggests

  person
  with learning disabilities

  )
• Condescending language (if you write

  obviously

  or

  everyone knows

  alex warns about it)
• Intolerant phrasing (if you write

  master

  and

  slave

  alex suggests

  primary

  and

  replica

  )
• Profanities (if you write

  butt

  🍑 alex warns about it)

…and much more!

Note: alex assumes good intent: that you don’t mean to offend!

See

retext-equality

retext-profanities

alex ignores words meant literally, so

“he”

He — ...

Integrations

• Atom —

  get-alex/atom-linter-alex

• Sublime —

  sindresorhus/SublimeLinter-contrib-alex

• Gulp —

  dustinspecker/gulp-alex

• Slack —

  keoghpe/alex-slack

• Ember —

  yohanmishkin/ember-cli-alex

• Probot —

  swinton/linter-alex

• GitHub Actions —

  brown-ccv/alex-recommends

• GitHub Actions (reviewdog) —

  reviewdog/action-alex

• Vim —

  w0rp/ale

• Browser extension —

  skn0tt/alex-browser-extension

• Contentful -

  stefanjudis/alex-js-contentful-ui-extension

• Figma -

  nickradford/figma-plugin-alex

• VSCode -

  tlahmann/vscode-alex

Ignoring files

The CLI searches for files with a markdown or text extension when given directories (so

$ alex .

readme.md

path/to/file.txt

.alexignore

.alexignore

The CLI will sometimes search for files. To prevent files from being found, add a file named

.alexignore

alex

.eslintignore

.gitignore

For example, when working in

~/path/to/place

to

place

~

The ignore file for this project itself looks like this:

# `node_modules` is ignored by default.
example.md

Control

Sometimes alex makes mistakes:

A message for this sentence will pop up.

Yields:

readme.md
  1:15-1:18  warning  `pop` may be insensitive, use `parent` instead  dad-mom  retext-equality

⚠ 1 warning

HTML comments in Markdown can be used to ignore them:

A message for this sentence will not pop up.

Yields:

readme.md: no issues found

ignore

disable

enable

A message for this sentence will not pop up.
A message for this sentence will also not pop up.
Yet another sentence where a message will not pop up.


A message for this sentence will pop up.

Yields:

readme.md
  9:15-9:18  warning  `pop` may be insensitive, use `parent` instead  dad-mom  retext-equality

⚠ 1 warning

Multiple messages can be controlled in one go:

…and all messages can be controlled by omitting all rule identifiers:

Configuration

You can control alex through

.alexrc

{
  "allow": ["boogeyman-boogeywoman"]
}

…you can use YAML if the file is named

.alexrc.yml

.alexrc.yaml

allow:
  - dad-mom

…you can also use JavaScript if the file is named

.alexrc.js

// But making it random like this is a bad idea!
exports.profanitySureness = Math.floor(Math.random() * 3)

…and finally it is possible to use an

alex

package.json

{
  …
  "alex": {
    "noBinary": true
  },
  …
}

The

allow

undefined

undefined

The

deny

undefined

undefined

You cannot use both

allow

deny

The

noBinary

false

true

he and she

garbageman or
garbagewoman

false

The

profanitySureness

0

cuss

| Rating | Use as a profanity | Use in clean text | Example | | ------ | ------------------ | ----------------- | -------- | | 2 | likely | unlikely |

asshat

addict

beaver

The

profanitySureness

1

1

2

0

CLI

Let’s say

example.md

The boogeyman wrote all changes to the **master server**. Thus, the slaves
were read-only copies of master. But not to worry, he was a cripple.

Now, run alex on

example.md

$ alex example.md

Yields:

example.md
   1:5-1:14  warning  `boogeyman` may be insensitive, use `boogeymonster` instead                boogeyman-boogeywoman  retext-equality
  1:42-1:48  warning  `master` / `slaves` may be insensitive, use `primary` / `replica` instead  master-slave           retext-equality
  1:69-1:75  warning  Don’t use `slaves`, it’s profane                                           slaves                 retext-profanities
  2:52-2:54  warning  `he` may be insensitive, use `they`, `it` instead                          he-she                 retext-equality
  2:61-2:68  warning  `cripple` may be insensitive, use `person with a limp` instead             gimp                   retext-equality

⚠ 5 warnings

See

$ alex --help

When no input files are given to alex, it searches for files in the current directory,

doc

, and

docs

. If

--mdx

is given, it searches for

mdx

extensions. If

--html

is given, it searches for

htm

and

html

extensions. Otherwise, it searches for

txt

,

text

,

md

,

mkd

,

mkdn

,

mkdown

,

ron

, and

markdown

extensions.

API

This package is ESM only: Node 12+ is needed to use it and it must be

import

require

npm:

$ npm install alex --save

This package exports the identifiers

markdown

mdx

html

text

markdown

markdown(value, config)

Check Markdown (ignoring syntax).

Parameters

• value

  (

  VFile

  or

  string

  ) — Markdown document

• config

  (

  Object

  , optional) — See the Configuration section

Returns

VFile

messages

Example

import alex from 'alex'

alex('We’ve confirmed his identity.').messages

Yields:

[
  [1:17-1:20: `his` may be insensitive, when referring to a person, use `their`, `theirs`, `them` instead] {
    message: '`his` may be insensitive, when referring to a ' +
      'person, use `their`, `theirs`, `them` instead',
    name: '1:17-1:20',
    reason: '`his` may be insensitive, when referring to a ' +
      'person, use `their`, `theirs`, `them` instead',
    line: 1,
    column: 17,
    location: { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'her-him',
    fatal: false,
    actual: 'his',
    expected: [ 'their', 'theirs', 'them' ]
  }
]

mdx(value, config)

Check MDX (ignoring syntax).

Note: the syntax for [email protected], while currently in beta, is used in alex.

Parameters

• value

  (

  VFile

  or

  string

  ) — MDX document

• config

  (

  Object

  , optional) — See the Configuration section

Returns

VFile

Example

import {mdx} from 'alex'

mdx('He walked to class.').messages

Yields:

[
  [1:12-1:14: `He` may be insensitive, use `They`, `It` instead] {
    reason: '`He` may be insensitive, use `They`, `It` instead',
    line: 1,
    column: 12,
    location: { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'he-she',
    fatal: false,
    actual: 'He',
    expected: [ 'They', 'It' ]
  }
]

html(value, config)

Check HTML (ignoring syntax).

Parameters

• value

  (

  VFile

  or

  string

  ) — HTML document

• config

  (

  Object

  , optional) — See the Configuration section

Returns

VFile

Example

import {html} from 'alex'

html('
He walked to class.
').messages

Yields:

[
  [1:18-1:20: `He` may be insensitive, use `They`, `It` instead] {
    message: '`He` may be insensitive, use `They`, `It` instead',
    name: '1:18-1:20',
    reason: '`He` may be insensitive, use `They`, `It` instead',
    line: 1,
    column: 18,
    location: { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'he-she',
    fatal: false,
    actual: 'He',
    expected: [ 'They', 'It' ]
  }
]

text(value, config)

Check plain text (as in, syntax is checked).

Parameters

• value

  (

  VFile

  or

  string

  ) — Text document

• config

  (

  Object

  , optional) — See the Configuration section

Returns

VFile

Example

import {markdown, text} from 'alex'

markdown('The boogeyman.').messages // => []
text('The boogeyman.').messages

Yields:

[
  [1:6-1:15: `boogeyman` may be insensitive, use `boogeymonster` instead] {
    message: '`boogeyman` may be insensitive, use `boogeymonster` instead',
    name: '1:6-1:15',
    reason: '`boogeyman` may be insensitive, use `boogeymonster` instead',
    line: 1,
    column: 6,
    location: Position { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'boogeyman-boogeywoman',
    fatal: false,
    actual: 'boogeyman',
    expected: [ 'boogeymonster' ]
  }
]

Workflow

The recommended workflow is to add alex to

package.json

You can opt to ignore warnings through alexrc files and control comments.

A

package.json

{
  "scripts": {
    "test-api": "ava",
    "test-doc": "alex",
    "test": "npm run test-api && npm run test-doc"
  },
  "devDependencies": {
    "alex": "^1.0.0",
    "ava": "^0.1.0"
  }
}

If you’re using Travis for continuous integration, set up something like the following in your

.travis.yml

 script:
 - npm test
+- alex --diff

Make sure to still install alex though!

If the

--diff

FAQ

This is stupid!

Not a question. And yeah, alex isn’t very smart. People are much better at this. But people make mistakes, and alex is there to help.

alex didn’t check “X”!

See

contributing.md

Why is this named alex?

It’s a nice unisex name, it was free on npm, I like it! :smile:

Further reading

No automated tool can replace studying inclusive communication and listening to the lived experiences of others. An error from

alex

alex

• The 18F Content Guide has a helpful list of links to other inclusive language guides used in journalism and academic writing.
• The Conscious Style Guide has articles on many nuanced topics of language. For example, the terms race and ethnicity mean different things, and choosing the right word is up to you. Likewise, a sentence that overgeneralizes about a group of people (e.g. “Developers love to code all day”) may not be noticed by

  alex

  , but it is not inclusive. A good human editor can step up to the challenge and find a better way to phrase things.
• Sometimes, the only way to know what is inclusive is to ask. In Disability is a nuanced thing, Nicolas Steenhout writes about how person-first language, such as “a person with a disability,” is not always the right choice.
• Language is always evolving. A term that is neutral one year ago can be problematic today. Projects like the Self-Defined Dictionary aim to collect the words that we use to define ourselves and others, and connect them with the history and some helpful advice.

• Unconsious bias is present in daily decisions and conversations and can show up in writing. Textio

  offers some examples of how descriptive adjective choice and tone can push some people away, and how regional language differences can cause confusion.

• Using complex sentences and uncommon vocabulary can lead to less inclusive content. This is described as literacy exclusion in this article by Harver. This is critical to be aware of if your content has a global audience, where a reader’s strongest language may not be the language you are writing in.

Contribute

See

contributing.md

get-alex/.github

support.md

This project has a Code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Origin story

Thanks to @iheanyi for raising the problem and @sindresorhus for inspiring me (@wooorm) to do something about it.

When alex launched, it got some traction on twitter and producthunt. Then there was a lot of press coverage.

Acknowledgments

Preliminary work for alex was done in 2015. The project was authored by @wooorm.

Lots of people helped since!

License

MIT © Titus Wormer