docs: Add 'Why this rule is important' sections to rule docs (#1723)

coliff · Copilot · web-flow · commit 8a3a247ff2f1 · 2025-09-11T14:03:53.000+09:00
* Add 'Why this rule is important' sections to rule docs

Added explanations to multiple rule documentation files describing the importance of each rule for accessibility, SEO, and code quality. Also updated the configuration example to include the new 'form-method-require' rule and fixed changelog issue links.

* Update website/src/content/docs/changelog.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/website/src/content/docs/changelog.mdx b/website/src/content/docs/changelog.mdx
@@ -8,9 +8,9 @@ import { Badge } from '@astrojs/starlight/components'
 ## 1.7.0 _(2025-09-11)_
 
 - <Badge text="Feat" size="small" /> New rule: [`form-method-require`](/rules/form-method-require/)
-  [#1670](https://github.com/htmlhint/HTMLHint/issues/1670)
+  [#1670](https://github.com/htmlhint/HTMLHint/issues/1721)
 - <Badge text="Feat" size="small" /> New rule: [`link-rel-canonical-require`](/rules/link-rel-canonical-require/)
-  [#1671](https://github.com/htmlhint/HTMLHint/issues/1671)
+  [#1671](https://github.com/htmlhint/HTMLHint/issues/1710)
 
 ## 1.6.3 _(2025-06-18)_
 
diff --git a/website/src/content/docs/configuration.md b/website/src/content/docs/configuration.md
@@ -55,6 +55,7 @@ An example configuration file (with all rules disabled):
     "doctype-first": false,
     "doctype-html5": false,
     "empty-tag-not-self-closed": false,
+    "form-method-require": false,
     "frame-title-require": false,
     "h1-require": false,
     "head-script-disabled": false,
diff --git a/website/src/content/docs/rules/alt-require.mdx b/website/src/content/docs/rules/alt-require.mdx
@@ -34,3 +34,7 @@ Level: <Badge text="Warning" variant="caution" />
 <input type="image" />
 <area shape="circle" coords="180,139,14" href="test.html" />
 ```
+
+### Why this rule is important
+
+The alt attribute is used to provide alternative text for images, which helps improve accessibility for users who cannot see the image. It also helps with SEO by providing context for the image.
diff --git a/website/src/content/docs/rules/attr-lowercase.mdx b/website/src/content/docs/rules/attr-lowercase.mdx
@@ -40,3 +40,7 @@ Level: <Badge text="Error" variant="danger" />
 ```html
 <img SRC="test.png" ALT="test" />
 ```
+
+### Why this rule is important
+
+Lowercase attribute names are required for HTML5 compliance and to ensure consistency across different HTML elements.
diff --git a/website/src/content/docs/rules/attr-no-duplication.mdx b/website/src/content/docs/rules/attr-no-duplication.mdx
@@ -26,3 +26,7 @@ Level: <Badge text="Error" variant="danger" />
 ```html
 <img src="a.png" src="b.png" />
 ```
+
+### Why this rule is important
+
+Duplicate attributes can cause unexpected behavior and make the code harder to read and maintain.
diff --git a/website/src/content/docs/rules/attr-whitespace.mdx b/website/src/content/docs/rules/attr-whitespace.mdx
@@ -28,3 +28,7 @@ Level: <Badge text="Error" variant="danger" />
 <div title="a "></div>
 <div title=" a "></div>
 ```
+
+### Why this rule is important
+
+Leading or trailing spaces inside attribute values can cause unexpected behavior and make the code harder to read and maintain.
diff --git a/website/src/content/docs/rules/doctype-first.mdx b/website/src/content/docs/rules/doctype-first.mdx
@@ -39,3 +39,7 @@ Level: <Badge text="Error" variant="danger" />
 <!DOCTYPE html>
 <html></html>
 ```
+
+### Why this rule is important
+
+The DOCTYPE declaration is required for HTML5 compliance and to ensure that the document is parsed correctly.
diff --git a/website/src/content/docs/rules/h1-require.mdx b/website/src/content/docs/rules/h1-require.mdx
@@ -8,7 +8,7 @@ sidebar:
 
 import { Badge } from '@astrojs/starlight/components';
 
-A H1 heading element is required in HTML documents. The heading can not be empty. This rule ensures that the document has a clear and accessible structure, which is important for both users and search engines.
+A H1 heading element is required in HTML documents. The heading can not be empty.
 
 Level: <Badge text="Warning" variant="caution" />
 
@@ -36,3 +36,7 @@ Level: <Badge text="Warning" variant="caution" />
 ```html
 <html><body><h1>   </h1></body></html>
 ```
+
+### Why this rule is important
+
+The `<h1>` element is the main heading of the page and is used to provide a clear and concise title for the page. It is also used to help with SEO by providing a clear and concise title for the page.
diff --git a/website/src/content/docs/rules/html-lang-require.mdx b/website/src/content/docs/rules/html-lang-require.mdx
@@ -39,3 +39,7 @@ Level: <Badge text="Warning" variant="caution" />
 <!-- invalid BCP 47 lang value -->
 <html lang="-"></html>
 ```
+
+### Why this rule is important
+
+The lang attribute is used to declare the language of the document, which helps with SEO and accessibility.
diff --git a/website/src/content/docs/rules/id-unique.mdx b/website/src/content/docs/rules/id-unique.mdx
@@ -26,3 +26,7 @@ Level: <Badge text="Error" variant="danger" />
 ```html
 <div id="id1"></div><div id="id1"></div>
 ```
+
+### Why this rule is important
+
+Duplicate ID attributes can cause unexpected behavior and make the code harder to read and maintain.
diff --git a/website/src/content/docs/rules/input-requires-label.mdx b/website/src/content/docs/rules/input-requires-label.mdx
@@ -34,3 +34,7 @@ Level: <Badge text="Warning" variant="caution" />
 <label for="some-id"/><input id="some-id" type="password" />
 <input id="some-id" type="password" /> <label for="some-id"/>
 ```
+
+### Why this rule is important
+
+This rule ensures that the input element has a corresponding label element for accessibility compliance.
diff --git a/website/src/content/docs/rules/main-require.mdx b/website/src/content/docs/rules/main-require.mdx
@@ -8,7 +8,7 @@ sidebar:
 
 import { Badge } from '@astrojs/starlight/components';
 
-A `<main>` element is required within the `<body>` tag of HTML documents. This rule ensures that the document has a clear and accessible structure, which is important for both users and screen readers.
+A `<main>` element is required within the `<body>` tag of HTML documents.
 
 Level: <Badge text="Warning" variant="caution" />
 
@@ -36,3 +36,7 @@ Level: <Badge text="Warning" variant="caution" />
 ```html
 <html><body><header>Header</header><footer>Footer</footer></body></html>
 ```
+
+### Why this rule is important
+
+This rule ensures that the document has a clear and accessible structure, which is important for both users and screen readers.
diff --git a/website/src/content/docs/rules/tag-no-obsolete.mdx b/website/src/content/docs/rules/tag-no-obsolete.mdx
@@ -19,7 +19,7 @@ Level: <Badge text="Error" variant="danger" />
 
 ## Description
 
-This rule prevents the use of HTML tags that have been deprecated and are considered obsolete in HTML5. These tags are no longer supported by modern browsers and should be replaced with appropriate alternatives.
+This rule prevents the use of HTML tags that have been deprecated and are considered obsolete in HTML5.
 
 ### Obsolete tags include:
 
@@ -42,3 +42,7 @@ This rule prevents the use of HTML tags that have been deprecated and are consid
 <font color="red">Red text</font>
 <marquee>Scrolling text</marquee>
 ```
+
+### Why this rule is important
+
+These tags are no longer supported by modern browsers and should be replaced with appropriate alternatives.
diff --git a/website/src/content/docs/rules/title-require.mdx b/website/src/content/docs/rules/title-require.mdx
@@ -28,3 +28,7 @@ Level: <Badge text="Error" variant="danger" />
 <html><head><title></title></head></html>
 <html><title></title><head></head></html>
 ```
+
+### Why this rule is important
+
+The `<title>` element is used to provide a title for the document, which helps with SEO and accessibility.
