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

coliff · web-flow · commit 196e9f448a60 · 2025-09-18T00:51:19.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, along with further reading links where relevant. Also updated some headings for consistency.

Update further reading links to use markdown format

Replaced plain angle-bracketed URLs with markdown link syntax in the 'Further reading' sections of doctype-html5, frame-title-require, and main-require rule documentation for improved readability.

Update spec-char-escape.mdx

Update id-class-ad-disabled.mdx
diff --git a/website/src/content/docs/rules/doctype-html5.mdx b/website/src/content/docs/rules/doctype-html5.mdx
@@ -28,3 +28,9 @@ Level: <Badge text="Warning" variant="caution" />
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "https://www.w3.org/TR/html4/strict.dtd">
 <html></html>
 ```
+
+## Why this rule is important
+
+The DOCTYPE declaration is required for HTML5 compliance and to ensure that the document is parsed correctly.
+
+Further reading: [MDN Web Docs - Doctype](https://developer.mozilla.org/en-US/docs/Glossary/Doctype)
diff --git a/website/src/content/docs/rules/frame-title-require.mdx b/website/src/content/docs/rules/frame-title-require.mdx
@@ -35,3 +35,9 @@ Level: <Badge text="Warning" variant="caution" />
 <iframe src="content.html" title=""></iframe>
 <frame src="content.html">
 ```
+
+## Why this rule is important
+
+The `<frame>` or `<iframe>` element must have an accessible name to help screen readers and assistive technologies understand the content of the frame or iframe.
+
+Further reading: [Axe Rules - frame-title](https://dequeuniversity.com/rules/axe/4.8/frame-title)
diff --git a/website/src/content/docs/rules/id-class-ad-disabled.mdx b/website/src/content/docs/rules/id-class-ad-disabled.mdx
@@ -27,3 +27,7 @@ Level: <Badge text="Warning" variant="caution" />
 <div id="ad-container"></div>
 <div id="ad_container"></div>
 ```
+
+## Why this rule is important
+
+Using `ad` in `id` or `class` attributes can cause elements to be hidden by ad-blocking software, which may break the layout or hide important content.
diff --git a/website/src/content/docs/rules/inline-style-disabled.mdx b/website/src/content/docs/rules/inline-style-disabled.mdx
@@ -20,3 +20,7 @@ Level: <Badge text="Warning" variant="caution" />
 ```html
 <div style="color:red"></div>
 ```
+
+## Why this rule is important
+
+Inline styles can make the code harder to read and maintain. They also make it harder to override styles with CSS.
diff --git a/website/src/content/docs/rules/link-rel-canonical-require.mdx b/website/src/content/docs/rules/link-rel-canonical-require.mdx
@@ -17,7 +17,7 @@ Level: <Badge text="Error" variant="danger" />
 - `true`: enable rule
 - `false`: disable rule
 
-## The following patterns are **not** considered rule violations
+### The following patterns are **not** considered rule violations
 
 ```html
 <!-- Valid canonical link with absolute URL -->
@@ -33,7 +33,7 @@ Level: <Badge text="Error" variant="danger" />
 <html><head><link rel="canonical" href="https://example.com/dresses/green-dresses#section1"></head></html>
 ```
 
-## The following patterns are considered rule violations
+### The following patterns are considered rule violations
 
 ```html
 <!-- Missing canonical link -->
diff --git a/website/src/content/docs/rules/main-require.mdx b/website/src/content/docs/rules/main-require.mdx
@@ -38,3 +38,5 @@ Level: <Badge text="Warning" variant="caution" />
 ### 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.
+
+Further reading: [Axe Rules - landmark-one-main](https://dequeuniversity.com/rules/axe/4.9/landmark-one-main)
diff --git a/website/src/content/docs/rules/meta-description-require.mdx b/website/src/content/docs/rules/meta-description-require.mdx
@@ -38,3 +38,12 @@ Level: <Badge text="Error" variant="danger" />
 <!-- Meta description outside head tag -->
 <html><meta name="description" content="A description"><head></head></html>
 ```
+
+## Why this rule is important
+
+The `<meta name="description">` tag is used to provide a description of the page, which helps with SEO.
+
+Further reading:
+
+- [MDN Web Docs - Setting a document meta description](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/content#setting_a_document_meta_description)
+- [Google Search Central - Meta descriptions](https://developers.google.com/search/docs/appearance/snippet#meta-descriptions)
diff --git a/website/src/content/docs/rules/meta-viewport-require.mdx b/website/src/content/docs/rules/meta-viewport-require.mdx
@@ -35,3 +35,7 @@ Level: <Badge text="Error" variant="danger" />
 <!-- Whitespace-only meta viewport content -->
 <html><head><meta name="viewport" content=" "></head></html>
 ```
+
+## Why this rule is important
+
+The `<meta name="viewport">` tag is used to control the viewport of the page, which helps with responsive design.
diff --git a/website/src/content/docs/rules/spec-char-escape.mdx b/website/src/content/docs/rules/spec-char-escape.mdx
@@ -28,3 +28,7 @@ Level: <Badge text="Error" variant="danger" />
 ```html
 <span>aaa>bbb<ccc</span>
 ```
+
+## Why this rule is important
+
+Special HTML characters like `<`, `>`, and `&` must be escaped to prevent them from being interpreted as HTML tags or entities. This avoids rendering issues and potential cross-site scripting (XSS) vulnerabilities.
