Update MD041/first-line-heading to recognize HTML headings (fixes #366).

demo/markdownlint-browser.js

@@ -3558,11 +3558,24 @@ module.exports = {
         var tag = "h" + level;
         var foundFrontMatterTitle = frontMatterHasTitle(params.frontMatterLines, params.config.front_matter_title);
         if (!foundFrontMatterTitle) {
+            var htmlHeadingRe_1 = new RegExp("^<h" + level + "[ />]", "i");
             params.tokens.every(function (token) {
+                var isError = false;
                 if (token.type === "html_block") {
-                    return true;
+                    if (token.content.startsWith("<!--")) {
+                        // Ignore leading HTML comments
+                        return true;
+                    }
+                    else if (!htmlHeadingRe_1.test(token.content)) {
+                        // Something other than an HTML heading
+                        isError = true;
+                    }
                 }
-                if ((token.type !== "heading_open") || (token.tag !== tag)) {
+                else if ((token.type !== "heading_open") || (token.tag !== tag)) {
+                    // Something other than a Markdown heading
+                    isError = true;
+                }
+                if (isError) {
                     addErrorContext(onError, token.lineNumber, token.line);
                 }
                 return false;

doc/Rules.md

@@ -1588,6 +1588,16 @@ To fix this, add a top-level heading to the beginning of the file:
 This is a file with a top-level heading
 ```
 
+Because it is common for projects on GitHub to use an image for the heading of
+`README.md` and that is not well-supported by Markdown, HTML headings are also
+permitted by this rule. For example:
+
+```markdown
+<h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
+
+This is a file with a top-level HTML heading
+```
+
 Note: The `level` parameter can be used to change the top-level (ex: to h2) in cases
 where an h1 is added externally.
 

lib/md041.js

@@ -17,11 +17,22 @@ module.exports = {
         params.config.front_matter_title
       );
     if (!foundFrontMatterTitle) {
+      const htmlHeadingRe = new RegExp(`^<h${level}[ />]`, "i");
       params.tokens.every((token) => {
+        let isError = false;
         if (token.type === "html_block") {
-          return true;
+          if (token.content.startsWith("<!--")) {
+            // Ignore leading HTML comments
+            return true;
+          } else if (!htmlHeadingRe.test(token.content)) {
+            // Something other than an HTML heading
+            isError = true;
+          }
+        } else if ((token.type !== "heading_open") || (token.tag !== tag)) {
+          // Something other than a Markdown heading
+          isError = true;
         }
-        if ((token.type !== "heading_open") || (token.tag !== tag)) {
+        if (isError) {
           addErrorContext(onError, token.lineNumber, token.line);
         }
         return false;

test/h1-as-top-level-heading.md

@@ -0,0 +1,7 @@
+<h1>H1 as Top-Level Heading</h1>
+
+Text
+
+<!-- markdownlint-configure-file {
+    "no-inline-html": false
+} -->

test/h1-image-as-top-level-heading.md

@@ -0,0 +1,7 @@
+<h1 align="center"><img src="https://placekitten.com/300/150"/></h1>
+
+Text
+
+<!-- markdownlint-configure-file {
+    "no-inline-html": false
+} -->

test/h2-as-top-level-heading.md

@@ -0,0 +1,10 @@
+<H2>H2 as Top-Level Heading</H2>
+
+Text
+
+<!-- markdownlint-configure-file {
+    "first-line-heading": {
+        "level": 2
+    },
+    "no-inline-html": false
+} -->

test/h3-as-top-level-heading.md

@@ -0,0 +1,7 @@
+<h3>H3 as Top-Level Heading {MD041}</h3>
+
+Text
+
+<!-- markdownlint-configure-file {
+    "no-inline-html": false
+} -->