Add level parameter to MD002/MD025/MD041 (fixes #19).

README.md

@@ -45,7 +45,7 @@ playground for learning and exploring.
 ## Rules / Aliases
 
 * **MD001** *header-increment* - Header levels should only increment by one level at a time
-* **MD002** *first-header-h1* - First header should be a h1 header
+* **MD002** *first-header-h1* - First header should be a top level header
 * **MD003** *header-style* - Header style
 * **MD004** *ul-style* - Unordered list style
 * **MD005** *list-indent* - Inconsistent indentation for list items at the same level

doc/Rules.md

@@ -34,12 +34,14 @@ level at a time:
 
     ### Another Header 3
 
-## MD002 - First header should be a h1 header
+## MD002 - First header should be a top level header
 
 Tags: headers
 
 Aliases: first-header-h1
 
+Parameters: level (number; default 1)
+
 This rule is triggered when the first header in the document isn't a h1 header:
 
     ## This isn't a H1 header
@@ -52,6 +54,9 @@ The first header in the document should be a h1 header:
 
     ## Then use a H2 for subsections
 
+Note: The `level` parameter can be used to change the top level (ex: to h2) in
+cases where an h1 is added externally.
+
 ## MD003 - Header style
 
 Tags: headers
@@ -535,6 +540,8 @@ Tags: headers
 
 Aliases: single-h1
 
+Parameters: level (number; default 1)
+
 This rule is triggered when a top level header is in use (the first line of
 the file is a h1 header), and more than one h1 header is in use in the
 document:
@@ -558,6 +565,9 @@ serves as the title for the document. If this convention is in use, then there
 can not be more than one title for the document, and the entire document
 should be contained within this header.
 
+Note: The `level` parameter can be used to change the top level (ex: to h2) in
+cases where an h1 is added externally.
+
 ## MD026 - Trailing punctuation in header
 
 Tags: headers
@@ -1001,6 +1011,8 @@ Tags: headers
 
 Aliases: first-line-h1
 
+Parameters: level (number; default 1)
+
 This rule is triggered when the first line in the file isn't a top level (h1)
 header:
 
@@ -1016,6 +1028,9 @@ To fix this, add a header to the top of your file:
     This is a file with a top level header
     ```
 
+Note: The `level` parameter can be used to change the top level (ex: to h2) in
+cases where an h1 is added externally.
+
 ## MD042 - No empty links
 
 Tags: links

lib/rules.js

@@ -170,13 +170,15 @@ module.exports = [
 
   {
     "name": "MD002",
-    "desc": "First header should be a h1 header",
+    "desc": "First header should be a top level header",
     "tags": [ "headers" ],
     "aliases": [ "first-header-h1" ],
     "func": function MD002(params, errors) {
+      var level = params.options.level || 1;
+      var tag = "h" + level;
       params.tokens.every(function forToken(token) {
         if (token.type === "heading_open") {
-          if (token.tag !== "h1") {
+          if (token.tag !== tag) {
             errors.push(token.lineNumber);
           }
           return false;
@@ -536,9 +538,11 @@ module.exports = [
     "tags": [ "headers" ],
     "aliases": [ "single-h1" ],
     "func": function MD025(params, errors) {
+      var level = params.options.level || 1;
+      var tag = "h" + level;
       var hasTopLevelHeading = false;
       filterTokens(params, "heading_open", function forToken(token) {
-        if (token.tag === "h1") {
+        if (token.tag === tag) {
           if (hasTopLevelHeading) {
             errors.push(token.lineNumber);
           } else if (token.lineNumber === 1) {
@@ -886,6 +890,8 @@ module.exports = [
     "tags": [ "headers" ],
     "aliases": [ "first-line-h1" ],
     "func": function MD041(params, errors) {
+      var level = params.options.level || 1;
+      var tag = "h" + level;
       var firstHeader = null;
       params.tokens.every(function forToken(token) {
         if (token.type === "heading_open") {
@@ -898,7 +904,7 @@ module.exports = [
       });
       if (!firstHeader ||
           (firstHeader.lineNumber !== 1) ||
-          (firstHeader.tag !== "h1")) {
+          (firstHeader.tag !== tag)) {
         errors.push(1);
       }
     }

test/alternate-top-level-header.json

@@ -0,0 +1,12 @@
+{
+  "default": true,
+  "MD002": {
+    "level": 2
+  },
+  "MD025": {
+    "level": 2
+  },
+  "MD041": {
+    "level": 2
+  }
+}

test/alternate-top-level-header.md

@@ -0,0 +1,3 @@
+## A level 2 top level header
+
+## Another one {MD025}

test/markdownlint-test.js

@@ -114,7 +114,7 @@ module.exports.resultFormatting = function resultFormatting(test) {
     var actualMessage = actualResult.toString();
     var expectedMessage =
       "./test/atx_header_spacing.md: 3: MD002" +
-      " First header should be a h1 header\n" +
+      " First header should be a top level header\n" +
       "./test/atx_header_spacing.md: 1: MD018" +
       " No space after hash on atx style header\n" +
       "./test/atx_header_spacing.md: 3: MD019" +
@@ -122,12 +122,12 @@ module.exports.resultFormatting = function resultFormatting(test) {
       "./test/atx_header_spacing.md: 5: MD019" +
       " Multiple spaces after hash on atx style header\n" +
       "./test/first_header_bad_atx.md: 1: MD002" +
-      " First header should be a h1 header";
+      " First header should be a top level header";
     test.equal(actualMessage, expectedMessage, "Incorrect message (name).");
     actualMessage = actualResult.toString(true);
     expectedMessage =
       "./test/atx_header_spacing.md: 3: first-header-h1" +
-      " First header should be a h1 header\n" +
+      " First header should be a top level header\n" +
       "./test/atx_header_spacing.md: 1: no-missing-space-atx" +
       " No space after hash on atx style header\n" +
       "./test/atx_header_spacing.md: 3: no-multiple-space-atx" +
@@ -135,7 +135,7 @@ module.exports.resultFormatting = function resultFormatting(test) {
       "./test/atx_header_spacing.md: 5: no-multiple-space-atx" +
       " Multiple spaces after hash on atx style header\n" +
       "./test/first_header_bad_atx.md: 1: first-header-h1" +
-      " First header should be a h1 header";
+      " First header should be a top level header";
     test.equal(actualMessage, expectedMessage, "Incorrect message (alias).");
     test.done();
   });
@@ -165,7 +165,7 @@ module.exports.resultFormattingSync = function resultFormattingSync(test) {
   var actualMessage = actualResult.toString();
   var expectedMessage =
     "./test/atx_header_spacing.md: 3: MD002" +
-    " First header should be a h1 header\n" +
+    " First header should be a top level header\n" +
     "./test/atx_header_spacing.md: 1: MD018" +
     " No space after hash on atx style header\n" +
     "./test/atx_header_spacing.md: 3: MD019" +
@@ -173,12 +173,12 @@ module.exports.resultFormattingSync = function resultFormattingSync(test) {
     "./test/atx_header_spacing.md: 5: MD019" +
     " Multiple spaces after hash on atx style header\n" +
     "./test/first_header_bad_atx.md: 1: MD002" +
-    " First header should be a h1 header";
+    " First header should be a top level header";
   test.equal(actualMessage, expectedMessage, "Incorrect message (name).");
   actualMessage = actualResult.toString(true);
   expectedMessage =
     "./test/atx_header_spacing.md: 3: first-header-h1" +
-    " First header should be a h1 header\n" +
+    " First header should be a top level header\n" +
     "./test/atx_header_spacing.md: 1: no-missing-space-atx" +
     " No space after hash on atx style header\n" +
     "./test/atx_header_spacing.md: 3: no-multiple-space-atx" +
@@ -186,7 +186,7 @@ module.exports.resultFormattingSync = function resultFormattingSync(test) {
     "./test/atx_header_spacing.md: 5: no-multiple-space-atx" +
     " Multiple spaces after hash on atx style header\n" +
     "./test/first_header_bad_atx.md: 1: first-header-h1" +
-    " First header should be a h1 header";
+    " First header should be a top level header";
   test.equal(actualMessage, expectedMessage, "Incorrect message (alias).");
   test.done();
 };
@@ -857,7 +857,7 @@ module.exports.readme = function readme(test) {
 };
 
 module.exports.doc = function doc(test) {
-  test.expect(289);
+  test.expect(292);
   fs.readFile("doc/Rules.md", shared.utf8Encoding,
     function readFile(err, contents) {
       test.ifError(err);