Refactor prose

…and improve some error messages

.remarkrc.js

@@ -3,7 +3,7 @@ exports.settings = {bullet: '*', paddedTable: false}
 exports.plugins = [
   require('./packages/remark-preset-lint-recommended'),
   require('./packages/remark-preset-lint-consistent'),
-  [require('remark-toc'), {tight: true, maxDepth: 2}],
+  [require('remark-toc'), {tight: true, maxDepth: 2, heading: 'contents'}],
   require('remark-comment-config'),
   require('remark-github'),
   require('remark-validate-links'),

doc/rules.md

@@ -4,10 +4,10 @@ This document describes how to configure rules and lists all available official
 rules.  Each rule is a separate package. See their readme’s for more
 information.
 
-## Table of Contents
+## Contents
 
 *   [Configuration](#configuration)
-*   [List of Rules](#list-of-rules)
+*   [List of rules](#list-of-rules)
 
 ## Configuration
 
@@ -16,15 +16,15 @@ information.
 ```js
 remark()
   .use(require('remark-lint-final-newline'), false)
-  // ...
+  // …
 ```
 
 `true` turns a rule on again:
 
 ```js
 remark()
   .use(require('remark-lint-final-newline'), true)
-  // ...
+  // …
 ```
 
 Rules can be configured with a severity too.  The following ignores all
@@ -33,24 +33,24 @@ messages from the plugin:
 ```js
 remark()
   .use(require('remark-lint-final-newline'), [0])
-  // ...
+  // …
 ```
 
-...and passing `[1]` explicitly sets the normal behaviour (warn for problems).
+…and passing `[1]` explicitly sets the normal behavior (warn for problems).
 To trigger an error instead of a warning, pass `2`:
 
 ```js
 remark()
   .use(require('remark-lint-final-newline'), [2])
-  // ...
+  // …
 ```
 
 It’s also possible to pass both a severity and configuration:
 
 ```js
 remark()
   .use(require('remark-lint-maximum-line-length'), [2, 70])
-  // ...
+  // …
 ```
 
 Lastly, strings can also be passed, instead of numbers:
@@ -60,21 +60,21 @@ Lastly, strings can also be passed, instead of numbers:
 ```js
 remark()
   .use(require('remark-lint-maximum-line-length'), ['error', 70])
-  // ...
+  // …
 ```
 
-## List of Rules
+## List of rules
 
 This lists contains all “official” rules, developed in this repository.
 For rules developed outside of this repo, view the [List of External
 Rules][external].
 
 <!--rules start-->
 
-*   [`blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-blockquote-indentation) — warn when blockquotes are either indented too much or too little
+*   [`blockquote-indentation`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-blockquote-indentation) — warn when block quotes are either indented too much or too little
 *   [`checkbox-character-style`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-checkbox-character-style) — warn when list item checkboxes violate a given style
 *   [`checkbox-content-indent`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-checkbox-content-indent) — warn when list item checkboxes are followed by too much whitespace
-*   [`code-block-style`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-code-block-style) — warn when code-blocks do not adhere to a given style
+*   [`code-block-style`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-code-block-style) — warn when code blocks do not adhere to a given style
 *   [`definition-case`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-definition-case) — warn when definition labels are not lowercase
 *   [`definition-spacing`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-definition-spacing) — warn when consecutive whitespace is used in a definition
 *   [`emphasis-marker`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-emphasis-marker) — warn when emphasis markers violate the given style
@@ -95,8 +95,8 @@ Rules][external].
 *   [`list-item-spacing`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-list-item-spacing) — warn when list looseness is incorrect
 *   [`maximum-heading-length`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-maximum-heading-length) — warn when headings are too long
 *   [`maximum-line-length`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-maximum-line-length) — warn when lines are too long
-*   [`no-auto-link-without-protocol`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-auto-link-without-protocol) — warn for angle-bracketed links without protocol
-*   [`no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-blockquote-without-marker) — warn when blank lines without markers (\`>\`) are found in a blockquote
+*   [`no-auto-link-without-protocol`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-auto-link-without-protocol) — warn for angle bracketed links without protocol
+*   [`no-blockquote-without-marker`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-blockquote-without-marker) — warn when blank lines without markers (\`>\`) are found in a block quote
 *   [`no-consecutive-blank-lines`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-consecutive-blank-lines) — warn for too many consecutive blank lines
 *   [`no-duplicate-definitions`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-duplicate-definitions) — warn on duplicate definitions
 *   [`no-duplicate-headings`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-duplicate-headings) — warn on duplicate headings
@@ -114,9 +114,9 @@ Rules][external].
 *   [`no-heading-punctuation`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-heading-punctuation) — warn when headings end in illegal characters
 *   [`no-html`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-html) — warn when HTML nodes are used
 *   [`no-inline-padding`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-inline-padding) — warn when inline nodes are padded with spaces
-*   [`no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-literal-urls) — warn when URLs without angle-brackets are used
+*   [`no-literal-urls`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-literal-urls) — warn when URLs without angle brackets are used
 *   [`no-missing-blank-lines`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-missing-blank-lines) — warn when missing blank lines
-*   [`no-multiple-toplevel-headings`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-multiple-toplevel-headings) — warn when multiple top-level headings are used
+*   [`no-multiple-toplevel-headings`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-multiple-toplevel-headings) — warn when multiple top level headings are used
 *   [`no-paragraph-content-indent`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-paragraph-content-indent) — warn when the content in paragraphs are indented
 *   [`no-reference-like-url`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-reference-like-url) — warn when URLs are also defined identifiers
 *   [`no-shell-dollars`](https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-shell-dollars) — warn when shell code is prefixed by dollars

packages/remark-lint-blockquote-indentation/index.js

@@ -4,30 +4,30 @@
  * @license MIT
  * @module blockquote-indentation
  * @fileoverview
- *   Warn when blockquotes are indented too much or too little.
+ *   Warn when block quotes are indented too much or too little.
  *
  *   Options: `number` or `'consistent'`, default: `'consistent'`.
  *
  *   `'consistent'` detects the first used indentation and will warn when
- *   other blockquotes use a different indentation.
+ *   other block quotes use a different indentation.
  *
- * @example {"name": "valid.md", "setting": 4}
+ * @example {"name": "ok.md", "setting": 4}
  *
  *   >   Hello
  *
  *   Paragraph.
  *
  *   >   World
  *
- * @example {"name": "valid.md", "setting": 2}
+ * @example {"name": "ok.md", "setting": 2}
  *
  *   > Hello
  *
  *   Paragraph.
  *
  *   > World
  *
- * @example {"name": "invalid.md", "label": "input"}
+ * @example {"name": "not-ok.md", "label": "input"}
  *
  *   >  Hello
  *
@@ -39,10 +39,10 @@
  *
  *   > World
  *
- * @example {"name": "invalid.md", "label": "output"}
+ * @example {"name": "not-ok.md", "label": "output"}
  *
- *   5:3: Remove 1 space between blockquote and content
- *   9:3: Add 1 space between blockquote and content
+ *   5:3: Remove 1 space between block quote and content
+ *   9:3: Add 1 space between block quote and content
  */
 
 'use strict'
@@ -82,7 +82,7 @@ function blockquoteIndentation(tree, file, pref) {
           Math.abs(diff) +
           ' ' +
           plural('space', diff) +
-          ' between blockquote and content'
+          ' between block quote and content'
 
         file.message(reason, position.start(node.children[0]))
       }

packages/remark-lint-blockquote-indentation/package.json

@@ -1,7 +1,7 @@
 {
   "name": "remark-lint-blockquote-indentation",
   "version": "1.0.3",
-  "description": "remark-lint rule to warn when blockquotes are either indented too much or too little",
+  "description": "remark-lint rule to warn when block quotes are either indented too much or too little",
   "license": "MIT",
   "keywords": [
     "remark",

packages/remark-lint-blockquote-indentation/readme.md

@@ -10,12 +10,12 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-Warn when blockquotes are indented too much or too little.
+Warn when block quotes are indented too much or too little.
 
 Options: `number` or `'consistent'`, default: `'consistent'`.
 
 `'consistent'` detects the first used indentation and will warn when
-other blockquotes use a different indentation.
+other block quotes use a different indentation.
 
 ## Presets
 
@@ -28,7 +28,7 @@ This rule is included in the following presets:
 
 ## Example
 
-##### `valid.md`
+##### `ok.md`
 
 When configured with `2`.
 
@@ -46,7 +46,7 @@ Paragraph.
 
 No messages.
 
-##### `valid.md`
+##### `ok.md`
 
 When configured with `4`.
 
@@ -64,7 +64,7 @@ Paragraph.
 
 No messages.
 
-##### `invalid.md`
+##### `not-ok.md`
 
 ###### In
 
@@ -83,8 +83,8 @@ Paragraph.
 ###### Out
 
 ```text
-5:3: Remove 1 space between blockquote and content
-9:3: Add 1 space between blockquote and content
+5:3: Remove 1 space between block quote and content
+9:3: Add 1 space between block quote and content
 ```
 
 ## Install
@@ -100,16 +100,16 @@ npm install remark-lint-blockquote-indentation
 You probably want to use it on the CLI through a config file:
 
 ```diff
- ...
+ …
  "remarkConfig": {
    "plugins": [
-     ...
+     …
      "lint",
 +    "lint-blockquote-indentation",
-     ...
+     …
    ]
  }
- ...
+ …
 ```
 
 Or use it on the CLI directly
@@ -121,15 +121,15 @@ remark -u lint -u lint-blockquote-indentation readme.md
 Or use this on the API:
 
 ```diff
- var remark = require('remark');
- var report = require('vfile-reporter');
+ var remark = require('remark')
+ var report = require('vfile-reporter')
 
  remark()
    .use(require('remark-lint'))
 +  .use(require('remark-lint-blockquote-indentation'))
    .process('_Emphasis_ and **importance**', function (err, file) {
-     console.error(report(err || file));
-   });
+     console.error(report(err || file))
+   })
 ```
 
 ## Contribute
@@ -138,8 +138,8 @@ See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
 to get started.
 See [`support.md`][support] for ways to get help.
 
-This project has a [Code of Conduct][coc].
-By interacting with this repository, organisation, or community you agree to
+This project has a [code of conduct][coc].
+By interacting with this repository, organization, or community you agree to
 abide by its terms.
 
 ## License
@@ -168,7 +168,7 @@ abide by its terms.
 
 [collective]: https://opencollective.com/unified
 
-[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
+[chat-badge]: https://img.shields.io/badge/chat-spectrum.svg
 
 [chat]: https://spectrum.chat/unified/remark
 

packages/remark-lint-checkbox-character-style/index.js

@@ -26,47 +26,47 @@
  *   See [Using remark to fix your Markdown](https://github.com/remarkjs/remark-lint#using-remark-to-fix-your-markdown)
  *   on how to automatically fix warnings for this rule.
  *
- * @example {"name": "valid.md", "setting": {"checked": "x"}}
+ * @example {"name": "ok.md", "setting": {"checked": "x"}}
  *
  *   - [x] List item
  *   - [x] List item
  *
- * @example {"name": "valid.md", "setting": {"checked": "X"}}
+ * @example {"name": "ok.md", "setting": {"checked": "X"}}
  *
  *   - [X] List item
  *   - [X] List item
  *
- * @example {"name": "valid.md", "setting": {"unchecked": " "}}
+ * @example {"name": "ok.md", "setting": {"unchecked": " "}}
  *
  *   - [ ] List item
  *   - [ ] List item
  *   - [ ]··
  *   - [ ]
  *
- * @example {"name": "valid.md", "setting": {"unchecked": "\t"}}
+ * @example {"name": "ok.md", "setting": {"unchecked": "\t"}}
  *
  *   - [»] List item
  *   - [»] List item
  *
- * @example {"name": "invalid.md", "label": "input"}
+ * @example {"name": "not-ok.md", "label": "input"}
  *
  *   - [x] List item
  *   - [X] List item
  *   - [ ] List item
  *   - [»] List item
  *
- * @example {"name": "invalid.md", "label": "output"}
+ * @example {"name": "not-ok.md", "label": "output"}
  *
  *   2:4-2:5: Checked checkboxes should use `x` as a marker
  *   4:4-4:5: Unchecked checkboxes should use ` ` as a marker
  *
- * @example {"setting": {"unchecked": "!"}, "name": "invalid.md", "label": "output", "config": {"positionless": true}}
+ * @example {"setting": {"unchecked": "💩"}, "name": "not-ok.md", "label": "output", "config": {"positionless": true}}
  *
- *   1:1: Invalid unchecked checkbox marker `!`: use either `'\t'`, or `' '`
+ *   1:1: Incorrect unchecked checkbox marker `💩`: use either `'\t'`, or `' '`
  *
- * @example {"setting": {"checked": "!"}, "name": "invalid.md", "label": "output", "config": {"positionless": true}}
+ * @example {"setting": {"checked": "💩"}, "name": "not-ok.md", "label": "output", "config": {"positionless": true}}
  *
- *   1:1: Invalid checked checkbox marker `!`: use either `'x'`, or `'X'`
+ *   1:1: Incorrect checked checkbox marker `💩`: use either `'x'`, or `'X'`
  */
 
 'use strict'
@@ -97,15 +97,15 @@ function checkboxCharacterStyle(tree, file, pref) {
 
   if (pref.unchecked && unchecked[pref.unchecked] !== true) {
     file.fail(
-      'Invalid unchecked checkbox marker `' +
+      'Incorrect unchecked checkbox marker `' +
         pref.unchecked +
         "`: use either `'\\t'`, or `' '`"
     )
   }
 
   if (pref.checked && checked[pref.checked] !== true) {
     file.fail(
-      'Invalid checked checkbox marker `' +
+      'Incorrect checked checkbox marker `' +
         pref.checked +
         "`: use either `'x'`, or `'X'`"
     )