retext-codex-standard
Enforce codeX rules about language: this is a testing tool that automatically runs on English-language content produced by the codeX team to guard against common grammar, sensitivity, and simplicity errors.
Enforcement
- Acronym & term styling, like GeoJSON rather than geoJSON
- Brand styling, like codeX instead of codeX
- Simple language - includes retext-simplify to recommend plain language words
- Sensitive language - includes retext-equality
Installation
Install globally:
npm install -g retext-codex-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:
<!--codex ignore geojson OpenStreetMap-->
Example
$ retext-codex-standard bad.mdbad.md 1:19-1:22 warning OSM is jargon, use OpenStreetMap instead 1:40-1:46 warning codex is styled codeX 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` insteadSource: 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 codex'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 codex-specific rules about styling and casing brands and technical jargon.