Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
coliff merged 1 commit into from
Sep 17, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions website/src/content/docs/rules/doctype-html5.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
6 changes: 6 additions & 0 deletions website/src/content/docs/rules/frame-title-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
4 changes: 4 additions & 0 deletions website/src/content/docs/rules/id-class-ad-disabled.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 4 additions & 0 deletions website/src/content/docs/rules/inline-style-disabled.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 2 additions & 2 deletions website/src/content/docs/rules/link-rel-canonical-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand All @@ -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 -->
Expand Down
2 changes: 2 additions & 0 deletions website/src/content/docs/rules/main-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
9 changes: 9 additions & 0 deletions website/src/content/docs/rules/meta-description-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
4 changes: 4 additions & 0 deletions website/src/content/docs/rules/meta-viewport-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
4 changes: 4 additions & 0 deletions website/src/content/docs/rules/spec-char-escape.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.