From f3e332eb00e05a9c92401df83d141402ad090106 Mon Sep 17 00:00:00 2001
From: "Travis C. LaGrone" <22419287+travis-c-lagrone@users.noreply.github.com>
Date: Sat, 6 Jul 2019 04:24:25 -0500
Subject: [PATCH] Strike through deprecated rule headings

Changes:
- Formats the headings of deprecated rules using strikethrough in the 'Rules /
Aliases' section of the 'README.md' file and in the 'doc/Rules.md' file.
- Updates the 'readme' and 'doc' tests in the 'test/markdownlint-test.js' file
to permit their respective rule headings to be formatted using strikethrough.

Benefits:
- Indicates rule deprecation status 'at a glance'.

(fixes #203)
---
 README.md                 |  4 +++-
 doc/Rules.md              |  5 +++--
 test/markdownlint-test.js | 14 ++++++++++++--
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 53e9a800..d25e93f9 100644
--- a/README.md
+++ b/README.md
@@ -47,7 +47,7 @@ playground for learning and exploring.
 ## Rules / Aliases
 
 * **[MD001](doc/Rules.md#md001)** *heading-increment/header-increment* - Heading levels should only increment by one level at a time
-* **[MD002](doc/Rules.md#md002)** *first-heading-h1/first-header-h1* - First heading should be a top level heading
+* ~~**[MD002](doc/Rules.md#md002)** *first-heading-h1/first-header-h1* - First heading should be a top level heading~~
 * **[MD003](doc/Rules.md#md003)** *heading-style/header-style* - Heading style
 * **[MD004](doc/Rules.md#md004)** *ul-style* - Unordered list style
 * **[MD005](doc/Rules.md#md005)** *list-indent* - Inconsistent indentation for list items at the same level
@@ -92,6 +92,8 @@ playground for learning and exploring.
 
 See [Rules.md](doc/Rules.md) for more details.
 
+~~Struck through~~ rules are deprecated, and provided for backward-compatibility.
+
 > All rules with `heading` as part of their name are also available as `header`
 > aliases (e.g. `heading-increment` is also available as `header-increment`).
 > The use of `header` is deprecated and provided for backward-compatibility.
diff --git a/doc/Rules.md b/doc/Rules.md
index 53bb3a9d..01fd7452 100644
--- a/doc/Rules.md
+++ b/doc/Rules.md
@@ -3,7 +3,8 @@
 
 This document contains a description of all rules, what they are checking for,
 as well as an examples of documents that break the rule and corrected
-versions of the examples.
+versions of the examples. Any rule whose heading is ~~struck through~~ is
+deprecated, but still provided for backward-compatibility.
 
 <a name="md001"></a>
 
@@ -43,7 +44,7 @@ level at a time:
 
 <a name="md002"></a>
 
-## MD002 - First heading should be a top level heading
+## ~~MD002 - First heading should be a top level heading~~
 
 Tags: headings, headers
 
diff --git a/test/markdownlint-test.js b/test/markdownlint-test.js
index d3ccf997..aaa66043 100644
--- a/test/markdownlint-test.js
+++ b/test/markdownlint-test.js
@@ -19,6 +19,8 @@ const configSchema = require("../schema/markdownlint-config-schema.json");
 const homepage = packageJson.homepage;
 const version = packageJson.version;
 
+const deprecatedRuleNames = [ "MD002" ];
+
 function promisify(func, ...args) {
   return new Promise((resolve, reject) => {
     func(...args, (error, result) => {
@@ -1138,9 +1140,12 @@ module.exports.readme = function readme(test) {
             if (rule) {
               const ruleName = rule.names[0];
               const ruleAliases = rule.names.slice(1);
-              const expected = "**[" + ruleName + "](doc/Rules.md#" +
+              let expected = "**[" + ruleName + "](doc/Rules.md#" +
                 ruleName.toLowerCase() + ")** *" +
                 ruleAliases.join("/") + "* - " + rule.description;
+              if (deprecatedRuleNames.includes(ruleName)) {
+                expected = "~~" + expected + "~~";
+              }
               test.equal(token.content, expected, "Rule mismatch.");
             }
           } else if (inTags) {
@@ -1197,8 +1202,13 @@ module.exports.doc = function doc(test) {
             ruleHasAliases = false;
             test.ok(rule,
               "Missing rule implementation for " + token.content + ".");
+            const ruleName = rule.names[0];
+            let headingContent = ruleName + " - " + rule.description;
+            if (deprecatedRuleNames.includes(ruleName)) {
+              headingContent = "~~" + headingContent + "~~";
+            }
             test.equal(token.content,
-              rule.names[0] + " - " + rule.description,
+              headingContent,
               "Rule mismatch.");
             ruleUsesParams = rule.function.toString()
               .match(/params\.config\.[_a-z]*/gi);