Introduce markdownlint disable script

.eslintrc.js

@@ -14,5 +14,6 @@ module.exports = {
     "import/no-commonjs": "off",
     "filenames/match-regex": "off",
     "i18n-text/no-en": "off",
+    "eslint-comments/no-use": "off",
   },
 };

.gitignore

@@ -1 +1,2 @@
-node_modules
+node_modules
+markdown-violations.json

.markdownlint-cli2.cjs

@@ -9,4 +9,11 @@ const options = require('./index.js').init({
 module.exports = {
     config: options,
     customRules: ["./index.js"],
+    outputFormatters: [
+        ['markdownlint-cli2-formatter-pretty', {appendLink: true}], // ensures the error message includes a link to the rule documentation
+        [
+          'markdownlint-cli2-formatter-json',
+          {name: 'markdown-violations.json', spaces: 1}
+        ]
+    ]
 }

package.json

@@ -9,7 +9,8 @@
   "scripts": {
     "publish": "npm publish --access public --@github:registry=https://registry.npmjs.org",
     "test": "npm run lint && jest",
-    "lint": "markdownlint-cli2 \"**/*.{md,mdx}\" \"!node_modules\" \"!docs/rules\" \"!test/example.md\" && eslint .",
+    "markdownlint": "markdownlint-cli2 \"**/*.{md,mdx}\" \"!node_modules\" \"!docs/rules\" \"!test/example.md\"",
+    "lint": "npm run markdownlint && eslint .",
     "lint:fix": "npm run lint -- --fix"
   },
   "dependencies": {
@@ -20,7 +21,9 @@
     "eslint-plugin-github": "^4.3.7",
     "jest": "^28.1.3",
     "markdownlint": "^0.26.1",
-    "markdownlint-cli2": "^0.5.1"
+    "markdownlint-cli2": "^0.5.1",
+    "markdownlint-cli2-formatter-json": "^0.0.7",
+    "markdownlint-cli2-formatter-pretty": "^0.0.4"
   },
   "repository": {
     "type": "git",

script/markdownlint-disable.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+// Disables markdownlint rules in markdown files with same-line comments. This is
+// useful when introducing a new rule that causes many failures. The comments
+// can be fixed and removed at while updating the file later.
+//
+// Usage:
+//
+//  script/markdownlint-disable.js no-generic-link-text
+
+/* eslint-disable no-console */
+
+const fs = require("fs");
+const { spawn } = require("child_process");
+
+const rule = process.argv[2];
+if (!rule) {
+  console.error("Please specify a rule to disable."); // eslint-disable-line no-console
+  process.exit(1);
+}
+let verbose = false;
+if (process.argv[3] === "--verbose" || process.argv[3] === "-v") {
+  verbose = true;
+}
+
+// Cleanup from previous run
+if (fs.existsSync("markdown-violations.json")) {
+  fs.unlinkSync("markdown-violations.json");
+}
+
+console.log(`Disabling "${rule}" rule in markdown files...`); // eslint-disable-line no-console
+const childProcess = spawn("npm", ["run", "markdownlint", rule]);
+
+childProcess.stdout.on("data", (data) => {
+  if (verbose) console.log(data.toString());
+});
+
+childProcess.stderr.on("data", function (data) {
+  if (verbose) console.log(data.toString());
+});
+
+let matchingRulesFound = 0;
+childProcess.on("close", (code) => {
+  if (code === 0) {
+    console.log(`No violations for rule, "${rule}" found.`); // eslint-disable-line no-console
+    process.exit(0);
+  }
+
+  const markdownViolations = JSON.parse(
+    fs.readFileSync("markdown-violations.json", "utf8")
+  );
+  console.log(`${markdownViolations.length} violations found.`); // eslint-disable-line no-console
+
+  for (const { fileName, ruleNames, lineNumber } of markdownViolations) {
+    if (fileName.endsWith(".mdx")) {
+      // Skip mdx files for now, which support different comment format.
+      return;
+    }
+    if (ruleNames.includes(rule)) {
+      matchingRulesFound++;
+      const fileLines = fs.readFileSync(fileName, "utf8").split("\n");
+      const offendingLine = fileLines[lineNumber - 1];
+      fileLines[lineNumber - 1] = offendingLine.concat(
+        ` <!-- markdownlint-disable-line ${rule} -->`
+      );
+      fs.writeFileSync(fileName, fileLines.join("\n"), "utf8");
+    }
+  }
+
+  console.log(`${matchingRulesFound} violations ignored.`); // eslint-disable-line no-console
+});