Enable custom rules to use the micromark parser, export micromark helpers for reuse.

doc/CustomRules.md

@@ -14,9 +14,8 @@ built-in rules.
 For simple requirements like disallowing certain characters or patterns,
 the community-developed
 [markdownlint-rule-search-replace][markdownlint-rule-search-replace]
-plug-in can be used.
-This plug-in allows anyone to create a set of simple text-replacement rules in
-JSON without needing to write any code.
+plug-in can be used. This plug-in allows anyone to create a set of simple
+text-replacement rules without needing to write code.
 
 [markdownlint-rule-search-replace]: https://www.npmjs.com/package/markdownlint-rule-search-replace
 
@@ -27,29 +26,62 @@ to more information, one or more tags, and a function that implements the rule's
 behavior. That function is called once for each file/string input and is passed
 the parsed input and a function to log any violations.
 
-A simple rule implementation looks like:
+Custom rules can (should) operate on a structured set of tokens based on the
+[`micromark`][micromark] `parser` (this is preferred). Alternatively, custom
+rules can operate on a structured set of tokens based on the
+[`markdown-it`][markdown-it] `parser` (legacy support). Finally, custom rules
+can operate directly on text with the `none` `parser`.
+
+A simple rule implementation using the `micromark` parser to report a violation
+for any use of blockquotes might look like:
 
 ```javascript
 /** @type import("markdownlint").Rule */
 module.exports = {
-  "names": [ "any-blockquote" ],
+  "names": [ "any-blockquote-micromark" ],
+  "description": "Rule that reports an error for any blockquote",
+  "information": new URL("https://example.com/rules/any-blockquote"),
+  "tags": [ "test" ],
+  "parser": "micromark",
+  "function": (params, onError) => {
+    const blockquotes = params.parsers.micromark.tokens
+      .filter(((token) => token.type === "blockQuote"));
+    for (const blockquote of blockquotes) {
+      const lines = blockquote.endLine - blockquote.startLine + 1;
+      onError({
+        "lineNumber": blockquote.startLine,
+        "detail": "Blockquote spans " + lines + " line(s).",
+        "context": params.lines[blockquote.startLine - 1]
+      });
+    }
+  }
+}
+```
+
+That same rule implemented using the `markdown-it` parser might look like:
+
+```javascript
+/** @type import("markdownlint").Rule */
+module.exports = {
+  "names": [ "any-blockquote-markdown-it" ],
   "description": "Rule that reports an error for any blockquote",
   "information": new URL("https://example.com/rules/any-blockquote"),
   "tags": [ "test" ],
   "parser": "markdownit",
-  "function": function rule(params, onError) {
-    params.parsers.markdownit.tokens.filter(function filterToken(token) {
-      return token.type === "blockquote_open";
-    }).forEach(function forToken(blockquote) {
-      var lines = blockquote.map[1] - blockquote.map[0];
+  "function": (params, onError) => {
+    const blockquotes = params.parsers.markdownit.tokens
+      .filter(((token) => token.type === "blockquote_open"));
+    for (const blockquote of blockquotes) {
+      const [ startIndex, endIndex ] = blockquote.map;
+      const lines = endIndex - startIndex;
       onError({
         "lineNumber": blockquote.lineNumber,
         "detail": "Blockquote spans " + lines + " line(s).",
-        "context": blockquote.line.substr(0, 7)
+        "context": blockquote.line
       });
-    });
+    }
   }
-};
+}
 ```
 
 A rule is implemented as an `Object`:
@@ -62,9 +94,8 @@ A rule is implemented as an `Object`:
   about the rule.
 - `tags` is a required `Array` of `String` values that groups related rules for
   easier customization.
-- `parser` is a required `String` value `"markdownit" | "none"` that specifies
-  the parser data used via `params.parsers` (see below).
-  - Note: The value `"micromark"` is valid but is NOT currently supported.
+- `parser` is a required `String` value `"markdownit" | "micromark" | "none"`
+  that specifies the parser data used via `params.parsers` (see below).
 - `asynchronous` is an optional `Boolean` value that indicates whether the rule
   returns a `Promise` and runs asynchronously.
 - `function` is a required `Function` that implements the rule and is passed two
@@ -79,7 +110,10 @@ A rule is implemented as an `Object`:
         - `tokens` is an `Array` of [`markdown-it` `Token`s][markdown-it-token]
           with added `line` and `lineNumber` properties. (This property was
           previously on the `params` object.)
-      - Samples for `tokens` are available via [test snapshots][tokens].
+      - `micromark` is an `Object` that provides access to output from the
+        [`micromark`][micromark] parser.
+        - `tokens` is an `Array` of [`MicromarkToken`][micromark-token] objects.
+      - Samples for both `tokens` are available via [test snapshots][tokens].
     - `lines` is an `Array` of `String` values corresponding to the lines of the
       input file/string.
     - `frontMatterLines` is an `Array` of `String` values corresponding to any
@@ -152,6 +186,8 @@ exception.
 [markdown-it]: https://github.com/markdown-it/markdown-it
 [markdown-it-token]: https://markdown-it.github.io/markdown-it/#Token
 [markdownlint-rule]: https://www.npmjs.com/search?q=keywords:markdownlint-rule
+[micromark]: https://github.com/micromark/micromark
+[micromark-token]: ../lib/markdownlint.d.ts
 [rule-helpers]: https://www.npmjs.com/package/markdownlint-rule-helpers
 [options-custom-rules]: ../README.md#optionscustomrules
 [test-rules]: ../test/rules