docs: add eslint-plugin-markdown for JavaScript code samples in documentation

This applies our JavaScript linting to the JavaScript code samples in the markdown documentation files.

* Autofixes styling/formatting/whitespace
* Fixes and prevents syntax errors

Author: bmish

.eslintrc.js

@@ -6,7 +6,6 @@ module.exports = {
   extends: [
     'not-an-aardvark/node',
     'plugin:node/recommended',
-    'plugin:self/all',
   ],
   rules: {
     'comma-dangle': [
@@ -18,15 +17,37 @@ module.exports = {
       },
     ],
     'require-jsdoc': 'error',
-
-    'self/meta-property-ordering': 'off',
-    'self/require-meta-docs-url': 'off',
-    'self/report-message-format': ['error', '^[^a-z].*.$'],
   },
   overrides: [
+    {
+      files: ['lib/**/*.js', 'tests/**/*.js'],
+      extends: ['plugin:self/all'],
+      rules: {
+        'self/meta-property-ordering': 'off',
+        'self/report-message-format': ['error', '^[^a-z].*.$'],
+        'self/require-meta-docs-url': 'off',
+      },
+    },
     {
       files: ['tests/**/*.js'],
       env: { mocha: true },
     },
+    {
+      files: ['**/*.md'],
+      processor: 'markdown/markdown',
+    },
+    {
+      // Markdown code samples in documentation:
+      files: ['**/*.md/*.js'],
+      plugins: ['markdown', 'self'],
+      parserOptions: {
+        sourceType: 'module',
+      },
+      noInlineConfig: true,
+      rules: {
+        'no-undef': 'off',
+        'no-unused-vars': 'off',
+      },
+    },
   ],
 };

docs/rules/consistent-output.md

@@ -13,51 +13,45 @@ This rule aims to ensure that if any invalid test cases have output assertions,
 Examples of **incorrect** code for this rule:
 
 ```js
-/* eslint eslint-plugin/consistent-output: error */
-
 new RuleTester().run('example-rule', rule, {
   valid: [],
   invalid: [
     {
       code: 'foo',
       output: 'bar',
-      errors: ['baz']
+      errors: ['baz'],
     },
     {
       code: 'bar',
-      errors: ['baz']
-    }
-  ]
+      errors: ['baz'],
+    },
+  ],
 });
-
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
-/* eslint eslint-plugin/consistent-output: error */
-
 new RuleTester().run('example-rule', rule, {
   valid: [],
   invalid: [
     {
       code: 'foo',
       output: 'bar',
-      errors: ['baz']
+      errors: ['baz'],
     },
     {
       code: 'bar',
       output: 'qux',
-      errors: ['baz']
+      errors: ['baz'],
     },
     {
       code: 'foo',
       output: null, // asserts that there is no autofix
-      errors: ['baz']
-    }
-  ]
+      errors: ['baz'],
+    },
+  ],
 });
-
 ```
 
 ## Options

docs/rules/fixer-return.md

@@ -9,30 +9,28 @@ This rule enforces that fixer functions always return a value.
 Examples of **incorrect** code for this rule:
 
 ```js
-/* eslint eslint-plugin/fixer-return: error */
 module.exports = {
-    create: function(context) {
-        context.report( {
-            fix: function(fixer) {
-                fixer.foo();
-            }
-        });
-    }
+  create (context) {
+    context.report({
+      fix (fixer) {
+        fixer.foo();
+      },
+    });
+  },
 };
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
-/* eslint eslint-plugin/fixer-return: error */
 module.exports = {
-    create: function(context) {
-        context.report( {
-            fix: function(fixer) {
-                return fixer.foo();
-            }
-        });
-    }
+  create (context) {
+    context.report({
+      fix (fixer) {
+        return fixer.foo();
+      },
+    });
+  },
 };
 ```
 

docs/rules/meta-property-ordering.md

@@ -23,23 +23,23 @@ Examples of **incorrect** code for this rule:
 // invalid; wrong order.
 module.exports = {
   meta: {
-    docs: "",
-    type: "problem",
-    fixable: "code",
+    docs: '',
+    type: 'problem',
+    fixable: 'code',
   },
-  create() {},
-}
+  create () {},
+};
 
 // invalid; extra properties must be placed afterwards.
 module.exports = {
   meta: {
-    type: "problem",
-    fooooooooo: "foo",
-    docs: "",
-    fixable: "code",
+    type: 'problem',
+    fooooooooo: 'foo',
+    docs: '',
+    fixable: 'code',
   },
-  create() {},
-}
+  create () {},
+};
 ```
 
 Examples of **correct** code for this rule:
@@ -52,13 +52,13 @@ Examples of **correct** code for this rule:
 // valid;
 module.exports = {
   meta: {
-    type: "bar",
-    docs: "foo",
-    messages: ["zoo"],
-    fooooooooo: "foo",
+    type: 'bar',
+    docs: 'foo',
+    messages: ['zoo'],
+    fooooooooo: 'foo',
   },
-  create() {},
-}
+  create () {},
+};
 ```
 
 ## When Not To Use It

docs/rules/no-deprecated-context-methods.md

@@ -35,29 +35,29 @@ Examples of **incorrect** code for this rule:
 
 ```js
 module.exports = {
-  create(context) {
+  create (context) {
     return {
-      Program(node) {
+      Program (node) {
         const firstToken = context.getFirstToken(node);
-      }
-    }
-  }
-}
+      },
+    };
+  },
+};
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
 module.exports = {
-  create(context) {
+  create (context) {
     const sourceCode = context.getSourceCode();
 
     return {
-      Program(node) {
+      Program (node) {
         const firstToken = sourceCode.getFirstToken(node);
-      }
-    }
-  }
+      },
+    };
+  },
 };
 ```
 

docs/rules/no-deprecated-report-api.md

@@ -12,13 +12,9 @@ The following patterns are considered warnings:
 
 ```js
 module.exports = {
-  create(context) {
-
+  create (context) {
     context.report(node, 'This node is bad.');
-
-    context.report(node, loc, 'This node is bad.');
-
-  }
+  },
 };
 
 ```
@@ -27,13 +23,11 @@ The following patterns are not warnings:
 
 ```js
 module.exports = {
-  create(context) {
-
+  create (context) {
     context.report({ node, message: 'This node is bad.' });
 
     context.report({ node, loc, message: 'This node is bad.' });
-
-  }
+  },
 };
 ```
 

docs/rules/no-identical-tests.md

@@ -9,31 +9,25 @@ When a rule has a lot of tests, it's sometimes difficult to tell if any tests ar
 Examples of **incorrect** code for this rule:
 
 ```js
-/* eslint eslint-plugin/no-identical-tests: error */
-
-new RuleTester().run('foo', bar, {
-valid: [
-    { code: 'foo' },
-    { code: 'foo' }
-],
-invalid: []
+new RuleTester().run('foo', bar, {
+  valid: [
+    { code: 'foo' },
+    { code: 'foo' },
+  ],
+  invalid: [],
 });
-
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
-/* eslint eslint-plugin/no-identical-tests: error */
-
-new RuleTester().run('foo', bar, {
-valid: [
-    { code: 'foo' },
-    { code: 'bar' }
-],
-invalid: []
+new RuleTester().run('foo', bar, {
+  valid: [
+    { code: 'foo' },
+    { code: 'bar' },
+  ],
+  invalid: [],
 });
-
 ```
 
 ## When Not To Use It

docs/rules/no-missing-placeholders.md

@@ -6,7 +6,7 @@ Report messages in rules can have placeholders surrounded by curly brackets.
 context.report({
   node,
   message: '{{disallowedNode}} nodes are not allowed.',
-  data: { disallowedNode: node.type }
+  data: { disallowedNode: node.type },
 });
 
 // Resulting message: e.g. 'IfStatement nodes are not allowed.'
@@ -21,49 +21,43 @@ This rule aims to disallow missing placeholders in rule report messages.
 Examples of **incorrect** code for this rule:
 
 ```js
-/*eslint eslint-plugin/no-missing-placeholders: error*/
-
 module.exports = {
-  create(context) {
+  create (context) {
     context.report({
       node,
-      message: '{{something}} is wrong.'
+      message: '{{something}} is wrong.',
     });
 
     context.report({
       node,
       message: '{{something}} is wrong.',
-      data: { somethingElse: 'foo' }
+      data: { somethingElse: 'foo' },
     });
 
     context.report(node, '{{something}} is wrong.', { somethingElse: 'foo' });
-  }
+  },
 };
-
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
-/*eslint eslint-plugin/no-missing-placeholders: error*/
-
 module.exports = {
-  create(context) {
+  create (context) {
     context.report({
       node,
-      message: 'something is wrong.'
+      message: 'something is wrong.',
     });
 
     context.report({
       node,
       message: '{{something}} is wrong.',
-      data: { something: 'foo' }
+      data: { something: 'foo' },
     });
 
     context.report(node, '{{something}} is wrong.', { something: 'foo' });
-  }
+  },
 };
-
 ```
 
 ## When Not To Use It