@mapbox/copyeditor NPM

copyeditor

Catch insensitive, inconsiderate writing, assert the documentation style guide through retext-mapbox-styleguide plugin, and check spelling.

This is a fork of alex. MIT © Titus Wormer

Plugins

Copyeditor comes with the following retext plugins:

Installation

Install copyeditor:

npm install @mapbox/copyeditor --save-dev

Create a script in package.json and specify pages directory:

"scripts": {
  "test-content": "copyeditor src/pages"
},

Configuration

Create .copyeditorrc to configure Copyeditor:

{
  "allow": ["appropriate"],
  "off": ["retext-passive"]
}

allow is a list of rule IDs that you want to disable for the repository. See disabling rules for more information.
off is an array of retext plugins you wish to completely disable for a project. See Disable an entire rule source for a project for more information.

Reading the output

The output for copyeditor as the following parts:

Line number
Message
Rule ID
Rule source

src/pages/index.md
  52:216-52:220  error  Replace “info” with “information”, help keep the voice of our docs consistent  info          copyeditor (styleguide)

You will use the line number (52:216-52:220) and message (error Replace “info” with “information”, help keep the voice of our docs consistent) to identify where on the page the message is and how to fix it.

You will use the rule ID (info) when disabling rules and the rule source (styleguide) to understand where the rule is coming from in case you need to debug or make configuration updates to it.

Disable rules

Copyeditor cannot always parse meaning. You can disable a rule either for a single page, an entire repository, or across all repositories.

See Reading the output to find the rule ID, which you will reference when disabling rules.

For a single page

You can ignore a rule inline with an HTML comment:

<!--copyeditor ignore just-->
Just build with Mapbox.

You can disable copyeditor or a single rule for full blocks of text:

<!--copyeditor disable just-->
Just build with Mapbox.
<!--copyeditor enable just-->

A message for just this sentence will appear.

To ignore multiple rules for a page:

<!--copyeditor ignore however clear indicate-->
However, it was clear that you did not indicate you wanted the last donut.

For an entire repository

In .copyeditorrc, you can specify a list of rules to disable if there is no better alternative. The allow field is expected to be an array of rule identifier strings.

{
  "allow": ["info", "appropriate"]
}

For every repository

To disable a rule for every repository, edit the configuration files:

conf/equality.config.json - for retext-equality
conf/simplify.config.json - for retext-simplify
conf/profanities.config.json - for retext-profanities
conf/spell.config.json - for retext-spell

If the rule is from another source, create an issue in this repository.

💡 If the word is part of the Mapbox brand and is also case sensitive, add it to retext-mapbox-styleguide instead.

Disable an entire plugin for a project

In .copyeditorrc, you can specify a list of plugins to disable. The off field is expected to be an array with the list of plugin names:

{
  "off": ["retext-passive"]
}

You can disable retext-equality, retext-simplify, retext-passive, or retext-profanities.

Ignore specific files

If the are files that you do not want copyeditor to test, create a .copyeditorignore file in your repository's root that defines these file paths (kind of like .gitignore).

Sync configuration files

Periodically, you can run a script that will update all the plugin configuration files with rules that appears in more than one repository's .copyeditorrc file:

mbx env
node scripts/update-config.js
npm test -- -u

Commit any accepted changes generated by the script above. Note: the above script is not perfect and it may update spell.config.json with a rule that belongs in another configuration file.

Copyeditor API

Copyeditor also offers an API to test markdown, test, or HTML programmatically.

import copyeditor, { text, html } from '@mapbox/copyeditor';

async function myTest() {
  const messages = await copyeditor('A *markdown* string');
  // const messages = await text('A text string');
  // const messages = await html('<div>An HTML string</div>');
  console.log(messages);
}

retext