@mapbox/copyeditor v1.0.0-beta.5
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
- Installation
- Configuration
- Reading the output
- Disable rules
- Sync configuration files
- Copyeditor API
Plugins
Copyeditor comes with the following retext plugins:
- retext-mapbox-styleguide
- retext-repeated-words
- retext-indefinite-article
- retext-profanities
- retext-equality
- retext-simplify
- retext-passive
- retext-spell
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-equalityconf/simplify.config.json
- for retext-simplifyconf/profanities.config.json
- for retext-profanitiesconf/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);
}
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago