Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mapbox/retext-mapbox-standard
Enforce Mapbox rules about language.
https://github.com/mapbox/retext-mapbox-standard
docs-tests
Last synced: 3 months ago
JSON representation
Enforce Mapbox rules about language.
- Host: GitHub
- URL: https://github.com/mapbox/retext-mapbox-standard
- Owner: mapbox
- License: other
- Archived: true
- Created: 2016-01-13T22:13:13.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2020-06-15T19:37:08.000Z (about 4 years ago)
- Last Synced: 2024-03-19T00:03:25.571Z (4 months ago)
- Topics: docs-tests
- Language: JavaScript
- Homepage:
- Size: 58.6 KB
- Stars: 139
- Watchers: 10
- Forks: 15
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Lists
- awesome-retext - retext-mapbox-standard - Enforce Mapbox rules about language. (Built on retext)
README
# retext-mapbox-standard
[](https://circleci.com/gh/mapbox/retext-mapbox-standard)
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](https://github.com/wooorm/retext-simplify) to recommend
plain language words
* Sensitive language - includes [retext-equality](https://github.com/wooorm/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](https://github.com/wooorm/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:
```html
```
## Example
```sh
$ 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](https://github.com/wooorm/remark) the Markdown parser and [wooorm/retext](https://github.com/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](http://liquidmarkup.org/) tags, this tool also includes a step that removes them before validation.
[retext-simplify](https://github.com/wooorm/retext-simplify) and [retext-equality](https://github.com/wooorm/retext-equality) (the core of [wooorm/alex](https://github.com/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](https://github.com/mapbox/retext-mapbox-standard/wiki)