Skip to content
Enforce Mapbox rules about language.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Circle CI

Enforce Mapbox rules about language: this is a testing tool that automatically runs on English-language content produced by the Mapbox team to guard against common grammar, sensitivity, and simplicity errors.


  • Acronym & term styling, like GeoJSON rather than geoJSON
  • Brand styling, like Mapbox instead of MapBox
  • Simple language - includes retext-simplify to recommend plain language words
  • Sensitive language - includes retext-equality


Install globally:

npm install -g @mapbox/retext-mapbox-standard

More typically, this will be included as a devDependency and invoked through the test script.


Per-file exceptions can be enabled with comments, using syntax from remark-message-control.

For instance, in the list above where we needed to mention the word geoJSON, the list is preceded by the following comment so that it doesn't trigger a validation error in CI:

<!--mapbox ignore geojson OpenStreetMap-->


$ retext-mapbox-standard
  1:19-1:22  warning  OSM is jargon, use OpenStreetMap instead
  1:40-1:46  warning  MapBox is styled Mapbox
  2:40-2:47  warning  geoJSON should be styled GeoJSON
  4:50-4:55  warning  `crazy` may be insensitive, use `rude`, `mean`, `disgusting`, `vile`, `person with symptoms of mental illness`, `person with mental illness`, `person with symptoms of a mental disorder`, `person with a mental disorder` instead

⚠ 4 warnings


Implementation details for the interested, optional reading

This code is built on wooorm/remark the Markdown parser and wooorm/retext the natural language toolkit. These libraries avoid false-positives related to code syntax: we should never flag a spelling error in a URL, for instance. Since Mapbox's documentation also uses Liquid templating tags, this tool also includes a step that removes them before validation.

retext-simplify and retext-equality (the core of wooorm/alex) are used unmodified but with a bunch of loosened restrictions. lib/standard adds Mapbox-specific rules about styling and casing brands and technical jargon.

See Also & FAQ

You can’t perform that action at this time.