fix(rules): better error message for `heading-level`

docs/rules/__tests__/__snapshots__/heading-level.md.spec.ts.snap

@@ -12,7 +12,7 @@ Array [
         "column": 2,
         "context": undefined,
         "line": 2,
-        "message": "Heading level can only increase by one, expected h2",
+        "message": "Heading level can only increase by one, expected <h2> but got <h3>",
         "offset": 20,
         "ruleId": "heading-level",
         "selector": "h3",

src/rules/__snapshots__/heading-level.spec.ts.snap

 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`rule heading-level should contain documentation 1`] = `
+exports[`rule heading-level should contain documentation (with multiple h1) 1`] = `
 Object {
-  "description": "Validates heading level increments and order. Headings must start at h1 and can only increase one level at a time.",
+  "description": "Headings must start at <h1> and can only increase one level at a time.
+The headings should form a table of contents and make sense on its own.",
+  "url": "https://html-validate.org/rules/heading-level.html",
+}
+`;
+
+exports[`rule heading-level should contain documentation (without multiple h1) 1`] = `
+Object {
+  "description": "Headings must start at <h1> and can only increase one level at a time.
+The headings should form a table of contents and make sense on its own.
+
+Under the current configuration only a single <h1> can be present at a time in the document.",
   "url": "https://html-validate.org/rules/heading-level.html",
 }
 `;
@@ -17,7 +28,7 @@ Array [
         "column": 2,
         "context": undefined,
         "line": 1,
-        "message": "Initial heading level must be h1",
+        "message": "Initial heading level must be <h1> but got <h2>",
         "offset": 1,
         "ruleId": "heading-level",
         "selector": "h2",
@@ -28,7 +39,7 @@ Array [
         "column": 2,
         "context": undefined,
         "line": 6,
-        "message": "Heading level can only increase by one, expected h3",
+        "message": "Heading level can only increase by one, expected <h3> but got <h4>",
         "offset": 73,
         "ruleId": "heading-level",
         "selector": "h4",

src/rules/heading-level.spec.ts

@@ -37,7 +37,7 @@ describe("rule heading-level", () => {
 		expect(report).toBeInvalid();
 		expect(report).toHaveError(
 			"heading-level",
-			"Heading level can only increase by one, expected h2"
+			"Heading level can only increase by one, expected <h2> but got <h3>"
 		);
 	});
 
@@ -45,21 +45,20 @@ describe("rule heading-level", () => {
 		expect.assertions(2);
 		const report = htmlvalidate.validateString("<h2>heading 2</h2>");
 		expect(report).toBeInvalid();
-		expect(report).toHaveError("heading-level", "Initial heading level must be h1");
+		expect(report).toHaveError("heading-level", "Initial heading level must be <h1> but got <h2>");
 	});
 
 	it("should report error when multiple <h1> are used", () => {
 		expect.assertions(2);
 		const report = htmlvalidate.validateString("<h1>heading 1</h1><h1>heading 1</h1>");
 		expect(report).toBeInvalid();
-		expect(report).toHaveError("heading-level", "Multiple h1 are not allowed");
+		expect(report).toHaveError("heading-level", "Multiple <h1> are not allowed");
 	});
 
 	it("should not report error when multiple <h1> are used but allowed via option", () => {
 		expect.assertions(1);
 		htmlvalidate = new HtmlValidate({
 			rules: { "heading-level": ["error", { allowMultipleH1: true }] },
-			elements: ["html5", { "custom-heading": { heading: true } }],
 		});
 		const report = htmlvalidate.validateString("<h1>heading 1</h1><h1>heading 1</h1>");
 		expect(report).toBeValid();
@@ -77,8 +76,19 @@ describe("rule heading-level", () => {
 		expect(report.results).toMatchSnapshot();
 	});
 
-	it("should contain documentation", () => {
+	it("should contain documentation (without multiple h1)", () => {
+		expect.assertions(1);
+		htmlvalidate = new HtmlValidate({
+			rules: { "heading-level": ["error", { allowMultipleH1: false }] },
+		});
+		expect(htmlvalidate.getRuleDocumentation("heading-level")).toMatchSnapshot();
+	});
+
+	it("should contain documentation (with multiple h1)", () => {
 		expect.assertions(1);
+		htmlvalidate = new HtmlValidate({
+			rules: { "heading-level": ["error", { allowMultipleH1: true }] },
+		});
 		expect(htmlvalidate.getRuleDocumentation("heading-level")).toMatchSnapshot();
 	});
 });

src/rules/heading-level.ts

@@ -17,9 +17,17 @@ export default class HeadingLevel extends Rule<void, Options> {
 	}
 
 	public documentation(): RuleDocumentation {
+		const text: string[] = [];
+		text.push("Headings must start at <h1> and can only increase one level at a time.");
+		text.push("The headings should form a table of contents and make sense on its own.");
+		if (!this.options.allowMultipleH1) {
+			text.push("");
+			text.push(
+				"Under the current configuration only a single <h1> can be present at a time in the document."
+			);
+		}
 		return {
-			description:
-				"Validates heading level increments and order. Headings must start at h1 and can only increase one level at a time.",
+			description: text.join("\n"),
 			url: ruleDocumentationUrl(__filename),
 		};
 	}
@@ -39,7 +47,7 @@ export default class HeadingLevel extends Rule<void, Options> {
 			if (!this.options.allowMultipleH1 && level === 1) {
 				if (h1Count >= 1) {
 					const location = sliceLocation(event.location, 1);
-					this.report(event.target, `Multiple h1 are not allowed`, location);
+					this.report(event.target, `Multiple <h1> are not allowed`, location);
 					return;
 				}
 
@@ -57,13 +65,11 @@ export default class HeadingLevel extends Rule<void, Options> {
 			if (level !== expected) {
 				const location = sliceLocation(event.location, 1);
 				if (current > 0) {
-					this.report(
-						event.target,
-						`Heading level can only increase by one, expected h${expected}`,
-						location
-					);
+					const msg = `Heading level can only increase by one, expected <h${expected}> but got <h${level}>`;
+					this.report(event.target, msg, location);
 				} else {
-					this.report(event.target, `Initial heading level must be h${expected}`, location);
+					const msg = `Initial heading level must be <h${expected}> but got <h${level}>`;
+					this.report(event.target, msg, location);
 				}
 			}