Update main heading rules to accept preferred depth

Update `first-heading-level` and `no-multiple-toplevel-headings`
to accept a preferred main heading level.  The previous, and
default, state is defined as level 1 headings, but it’s now
possible to specify other levels as well.

Closes GH-51.

Author: michaelmior

doc/rules.md

@@ -403,18 +403,20 @@ Options: `boolean`, default: `false`.
 ### first-heading-level
 
 ```md
-  <!-- Valid: -->
+  <!-- Valid, when set to `1` -->
   # Foo
 
   ## Bar
 
-  <!-- Invalid: -->
+  <!-- Invalid, when set to `1` -->
   ## Foo
 
   # Bar
 ```
 
-  Warn when the first heading has a level other than `1`.
+  Warn when the first heading has a level other than a specified value.
+
+  Options: `number`, default: `1`.
 
 ### hard-break-spaces
 
@@ -950,19 +952,21 @@ Options: `boolean`, default: `false`.
 ### no-multiple-toplevel-headings
 
 ```md
-  <!-- Invalid: -->
+  <!-- Invalid, when set to `1` -->
   # Foo
 
   # Bar
 
-  <!-- Valid: -->
+  <!-- Valid, when set to `1` -->
   # Foo
 
   ## Bar
 ```
 
   Warn when multiple top-level headings are used.
 
+  Options: `number`, default: `1`.
+
 ### no-shell-dollars
 
 ````md

lib/rules/first-heading-level.js

@@ -4,14 +4,16 @@
  * @license MIT
  * @module first-heading-level
  * @fileoverview
- *   Warn when the first heading has a level other than `1`.
+ *   Warn when the first heading has a level other than a specified value.
+ *
+ *   Options: `number`, default: `1`.
  * @example
- *   <!-- Valid: -->
+ *   <!-- Valid, when set to `1` -->
  *   # Foo
  *
  *   ## Bar
  *
- *   <!-- Invalid: -->
+ *   <!-- Invalid, when set to `1` -->
  *   ## Foo
  *
  *   # Bar
@@ -29,21 +31,23 @@ var visit = require('unist-util-visit');
 var position = require('mdast-util-position');
 
 /**
- * Warn when the first heading has a level other than `1`.
+ * Warn when the first heading has a level other than a specified value.
  *
  * @param {Node} ast - Root node.
  * @param {File} file - Virtual file.
- * @param {*} preferred - Ignored.
+ * @param {number?} [preferred=1] - First heading level.
  * @param {Function} done - Callback.
  */
 function firstHeadingLevel(ast, file, preferred, done) {
+    var style = preferred && preferred !== true ? preferred : 1;
+
     visit(ast, 'heading', function (node) {
         if (position.generated(node)) {
             return null;
         }
 
-        if (node.depth !== 1) {
-            file.warn('First heading level should be `1`', node);
+        if (node.depth !== style) {
+            file.warn('First heading level should be `' + style + '`', node);
         }
 
         return false;

lib/rules/no-multiple-toplevel-headings.js

@@ -5,13 +5,15 @@
  * @module no-multiple-toplevel-headings
  * @fileoverview
  *   Warn when multiple top-level headings are used.
+ *
+ *   Options: `number`, default: `1`.
  * @example
- *   <!-- Invalid: -->
+ *   <!-- Invalid, when set to `1` -->
  *   # Foo
  *
  *   # Bar
  *
- *   <!-- Valid: -->
+ *   <!-- Valid, when set to `1` -->
  *   # Foo
  *
  *   ## Bar
@@ -33,10 +35,11 @@ var position = require('mdast-util-position');
  *
  * @param {Node} ast - Root node.
  * @param {File} file - Virtual file.
- * @param {*} preferred - Ignored.
+ * @param {number?} [preferred=1] - Top heading level.
  * @param {Function} done - Callback.
  */
 function noMultipleToplevelHeadings(ast, file, preferred, done) {
+    var style = preferred && preferred !== true ? preferred : 1;
     var topLevelheading = false;
 
     visit(ast, 'heading', function (node) {
@@ -46,7 +49,7 @@ function noMultipleToplevelHeadings(ast, file, preferred, done) {
             return;
         }
 
-        if (node.depth === 1) {
+        if (node.depth === style) {
             if (topLevelheading) {
                 pos = position.start(node);
 

test/fixtures/first-heading-level-invalid-second.md

@@ -0,0 +1 @@
+# Valid

test/fixtures/first-heading-level-valid-second.md

@@ -0,0 +1 @@
+## Valid

test/fixtures/no-multiple-toplevel-headings-invalid-second.md

@@ -0,0 +1,4 @@
+Another heading
+---------------
+
+## Another

test/fixtures/no-multiple-toplevel-headings-valid-second.md

@@ -0,0 +1,4 @@
+Valid
+---------------
+
+### Another heading

test/index.js

@@ -493,6 +493,14 @@ describe('Rules', function () {
 
             assertFile('first-heading-level-valid.md', []);
         });
+
+        describeSetting(2, function () {
+            assertFile('first-heading-level-invalid-second.md', [
+                'first-heading-level-invalid-second.md:1:1-1:8: First heading level should be `2`'
+            ]);
+
+            assertFile('first-heading-level-valid-second.md', []);
+        });
     });
 
     describeRule('heading-increment', function () {
@@ -719,6 +727,14 @@ describe('Rules', function () {
 
             assertFile('no-multiple-toplevel-headings-valid.md', []);
         });
+
+        describeSetting(2, function () {
+            assertFile('no-multiple-toplevel-headings-invalid-second.md', [
+                'no-multiple-toplevel-headings-invalid-second.md:4:1-4:11: Don’t use multiple top level headings (4:1)'
+            ]);
+
+            assertFile('no-multiple-toplevel-headings-valid-second.md', []);
+        });
     });
 
     describeRule('no-literal-urls', function () {