Skip to content
This repository has been archived by the owner on Apr 21, 2023. It is now read-only.

mapbox/retext-mapbox-standard

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 

retext-mapbox-standard

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.

Enforcement

  • 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

Installation

Install globally:

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

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

Configuration

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

Example

$ retext-mapbox-standard bad.md
bad.md
  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
Source: http://ncdj.org/style-guide/

⚠ 4 warnings

Architecture

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

About

Enforce Mapbox rules about language.

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published