Deprecate MD002/first-heading-h1 in favor of MD041/first-line-h1 (refs #169).

doc/Rules.md

@@ -51,6 +51,9 @@ Aliases: first-heading-h1, first-header-h1
 
 Parameters: level (number; default 1)
 
+> Note: *MD002 has been deprecated and is disabled by default.*
+> [MD041](#md041) offers an improved implementation of the rule.
+
 This rule is intended to ensure document headings start at the top level and
 is triggered when the first heading in the document isn't an h1 heading:
 
@@ -71,8 +74,6 @@ The first heading in the document should be an h1 heading:
 Note: The `level` parameter can be used to change the top level (ex: to h2) in
 cases where an h1 is added externally.
 
-See also: [MD041](#md041) for an improved version of this rule.
-
 <a name="md003"></a>
 
 ## MD003 - Heading style

lib/markdownlint.js

@@ -9,6 +9,8 @@ const markdownIt = require("markdown-it");
 const rules = require("./rules");
 const shared = require("./shared");
 
+const deprecatedRuleNames = [ "MD002" ];
+
 // Validates the list of rules for structure and reuse
 function validateRuleList(ruleList) {
   let result = null;
@@ -212,16 +214,19 @@ function mapAliasToRuleNames(ruleList) {
 
 // Apply (and normalize) config
 function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
-  const defaultKey = Object.keys(config).filter(function forKey(key) {
-    return key.toUpperCase() === "DEFAULT";
-  });
+  const defaultKey = Object.keys(config).filter(
+    (key) => key.toUpperCase() === "DEFAULT"
+  );
   const ruleDefault = (defaultKey.length === 0) || !!config[defaultKey[0]];
   const effectiveConfig = {};
-  ruleList.forEach(function forRule(rule) {
+  ruleList.forEach((rule) => {
     const ruleName = rule.names[0].toUpperCase();
     effectiveConfig[ruleName] = ruleDefault;
   });
-  Object.keys(config).forEach(function forKey(key) {
+  deprecatedRuleNames.forEach((ruleName) => {
+    effectiveConfig[ruleName] = false;
+  });
+  Object.keys(config).forEach((key) => {
     let value = config[key];
     if (value) {
       if (!(value instanceof Object)) {
@@ -231,7 +236,7 @@ function getEffectiveConfig(ruleList, config, aliasToRuleNames) {
       value = false;
     }
     const keyUpper = key.toUpperCase();
-    (aliasToRuleNames[keyUpper] || []).forEach(function forRule(ruleName) {
+    (aliasToRuleNames[keyUpper] || []).forEach((ruleName) => {
       effectiveConfig[ruleName] = value;
     });
   });

test/break-all-the-rules.json

@@ -1,5 +1,6 @@
 {
   "default": true,
+  "MD002": true,
   "MD041": true,
   "MD043": {
     "headings": [

test/detailed-results-MD001-MD010.json

@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD002": true
+}

test/first_heading_bad_atx.md

@@ -1 +1 @@
-## Heading {MD002}
+## Heading

test/first_heading_bad_setext.md

@@ -1,2 +1,2 @@
-Heading {MD002}
---------------
+Heading
+-------

test/front-matter-embedded.md

@@ -1,7 +1,7 @@
 Text text text
 
 ---
-layout: post {MD002} {MD022}
+layout: post {MD022}
 hard:	tab {MD010}
 title: embedded
 ---

test/front-matter-with-dashes.md

@@ -3,7 +3,7 @@ layout: post
 title: Title with ---
 tags: front matter
 ---
-## Heading {MD002}
+## Heading
 
 ---
 

test/markdownlint-test.js

@@ -140,7 +140,10 @@ module.exports.resultFormattingV0 = function resultFormattingV0(test) {
       "./test/atx_heading_spacing.md",
       "./test/first_heading_bad_atx.md"
     ],
-    "config": defaultConfig,
+    "config": {
+      "MD002": true,
+      "MD041": false
+    },
     "resultVersion": 0
   };
   markdownlint(options, function callback(err, actualResult) {
@@ -193,7 +196,10 @@ module.exports.resultFormattingSyncV0 = function resultFormattingSyncV0(test) {
       "./test/atx_heading_spacing.md",
       "./test/first_heading_bad_atx.md"
     ],
-    "config": defaultConfig,
+    "config": {
+      "MD002": true,
+      "MD041": false
+    },
     "resultVersion": 0
   };
   const actualResult = markdownlint.sync(options);
@@ -248,7 +254,10 @@ module.exports.resultFormattingV1 = function resultFormattingV1(test) {
       "./test/atx_heading_spacing.md",
       "./test/first_heading_bad_atx.md"
     ],
-    "config": defaultConfig,
+    "config": {
+      "MD002": true,
+      "MD041": false
+    },
     "resultVersion": 1
   };
   markdownlint(options, function callback(err, actualResult) {
@@ -347,7 +356,10 @@ module.exports.resultFormattingV2 = function resultFormattingV2(test) {
       "./test/atx_heading_spacing.md",
       "./test/first_heading_bad_atx.md"
     ],
-    "config": defaultConfig
+    "config": {
+      "MD002": true,
+      "MD041": false
+    }
   };
   markdownlint(options, function callback(err, actualResult) {
     test.ifError(err);
@@ -503,13 +515,11 @@ module.exports.defaultTrue = function defaultTrue(test) {
     test.ifError(err);
     const expectedResult = {
       "./test/atx_heading_spacing.md": {
-        "MD002": [ 3 ],
         "MD018": [ 1 ],
         "MD019": [ 3, 5 ],
         "MD041": [ 1 ]
       },
       "./test/first_heading_bad_atx.md": {
-        "MD002": [ 1 ],
         "MD041": [ 1 ]
       }
     };
@@ -555,13 +565,11 @@ module.exports.defaultUndefined = function defaultUndefined(test) {
     test.ifError(err);
     const expectedResult = {
       "./test/atx_heading_spacing.md": {
-        "MD002": [ 3 ],
         "MD018": [ 1 ],
         "MD019": [ 3, 5 ],
         "MD041": [ 1 ]
       },
       "./test/first_heading_bad_atx.md": {
-        "MD002": [ 1 ],
         "MD041": [ 1 ]
       }
     };
@@ -675,11 +683,9 @@ module.exports.disableTag = function disableTag(test) {
     test.ifError(err);
     const expectedResult = {
       "./test/atx_heading_spacing.md": {
-        "MD002": [ 3 ],
         "MD041": [ 1 ]
       },
       "./test/first_heading_bad_atx.md": {
-        "MD002": [ 1 ],
         "MD041": [ 1 ]
       }
     };
@@ -767,7 +773,6 @@ module.exports.styleAll = function styleAll(test) {
     const expectedResult = {
       "./test/break-all-the-rules.md": {
         "MD001": [ 3 ],
-        "MD002": [ 1 ],
         "MD003": [ 5, 30 ],
         "MD004": [ 8 ],
         "MD005": [ 12 ],
@@ -823,7 +828,6 @@ module.exports.styleRelaxed = function styleRelaxed(test) {
     const expectedResult = {
       "./test/break-all-the-rules.md": {
         "MD001": [ 3 ],
-        "MD002": [ 1 ],
         "MD003": [ 5, 30 ],
         "MD004": [ 8 ],
         "MD005": [ 12 ],
@@ -2649,7 +2653,6 @@ $$`
       test.ifError(err);
       const expected = {
         "string": {
-          "MD002": [ 1 ],
           "MD041": [ 1 ]
         }
       };

test/no_first_line_top_level_heading.md

@@ -1 +1 @@
-## Second level heading {MD041} {MD002}
+## Second level heading {MD041}

test/required-headings-missing-first.md

@@ -1,5 +1,5 @@
 text
 
-## Two {MD002} {MD043}
+## Two {MD043}
 
 ### Three