From 6621cf091e583c27f6af4898b51a52719eeaaba8 Mon Sep 17 00:00:00 2001
From: Christian Oliff <christian_oliff@trimble.com>
Date: Thu, 11 Sep 2025 14:00:42 +0900
Subject: [PATCH 1/2] 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.
---
 website/src/content/docs/changelog.mdx                  | 4 ++--
 website/src/content/docs/configuration.md               | 1 +
 website/src/content/docs/rules/alt-require.mdx          | 4 ++++
 website/src/content/docs/rules/attr-lowercase.mdx       | 4 ++++
 website/src/content/docs/rules/attr-no-duplication.mdx  | 4 ++++
 website/src/content/docs/rules/attr-whitespace.mdx      | 4 ++++
 website/src/content/docs/rules/doctype-first.mdx        | 4 ++++
 website/src/content/docs/rules/h1-require.mdx           | 6 +++++-
 website/src/content/docs/rules/html-lang-require.mdx    | 4 ++++
 website/src/content/docs/rules/id-unique.mdx            | 4 ++++
 website/src/content/docs/rules/input-requires-label.mdx | 4 ++++
 website/src/content/docs/rules/main-require.mdx         | 6 +++++-
 website/src/content/docs/rules/tag-no-obsolete.mdx      | 6 +++++-
 website/src/content/docs/rules/title-require.mdx        | 4 ++++
 14 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/website/src/content/docs/changelog.mdx b/website/src/content/docs/changelog.mdx
index 693fb4ec4..e0eedb915 100644
--- 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
index 0a620da7e..183f67430 100644
--- 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
index 65049e407..85566c90d 100644
--- 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
index 3c551feb2..667009ad3 100644
--- 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
index 2be572605..50aaff674 100644
--- 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
index e95f004aa..5c87018ce 100644
--- 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
index 5497f8a5b..02f1d9f29 100644
--- 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
index d0cef37fb..976aa7652 100644
--- 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
index 309eee5eb..484d8776a 100644
--- 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
index ccc061436..d9a68f4bd 100644
--- 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
index 5ec08a3b5..5303116de 100644
--- 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
index 4cb3498fa..0f948ab00 100644
--- 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
index 4edfbcece..0c8946f66 100644
--- 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
index 6d092e0a3..b8eab01df 100644
--- 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.

From 26847615dfb34d3015167aeaeef8474b512aa32c Mon Sep 17 00:00:00 2001
From: Christian Oliff <christianoliff@pm.me>
Date: Thu, 11 Sep 2025 14:02:03 +0900
Subject: [PATCH 2/2] Update website/src/content/docs/changelog.mdx

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 website/src/content/docs/changelog.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/src/content/docs/changelog.mdx b/website/src/content/docs/changelog.mdx
index e0eedb915..8a7b8a463 100644
--- a/website/src/content/docs/changelog.mdx
+++ b/website/src/content/docs/changelog.mdx
@@ -8,7 +8,7 @@ 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/1721
+  [#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/1710)