Skip to content

Update docs and config for rules and keywords #1738

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
merged 2 commits into from
Sep 29, 2025
Merged

Update docs and config for rules and keywords #1738

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
754022f
Update docs and config for rules and keywords
coliff Sep 29, 2025
6f6ff23
Update documentation rules and fix trailing newline
coliff Sep 29, 2025
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
1 change: 1 addition & 0 deletions .cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@
"nomix",
"noopener",
"npmjs",
"onclick",
"onttt",
"opencollective",
"ossf",
Expand Down
5 changes: 5 additions & 0 deletions .cursor/rules/general.mdc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,8 @@ alwaysApply: true
- The workflows should be named `<workflow-name>.yml`.
- All GitHub Actions should be pinned versions to avoid breaking changes (SHA-1).
- If using actions/checkout, it should have `persist-credentials: false` set.

## Documentation

- All documentation should be written in US English.
- For the 'Why this rule is important' section, always include a link to the relevant documentation and prefer MDN and Google documentation along with official documentation from the W3C.
4 changes: 4 additions & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,7 @@
- The workflows should be named `<workflow-name>.yml`.
- All GitHub Actions should be pinned versions to avoid breaking changes (SHA-1).
- If using actions/checkout, it should have `persist-credentials: false` set.

## GitHub Commit Messages

- If multiple changes are made then list changes using bullet points.
90 changes: 44 additions & 46 deletions website/src/content/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,52 +39,50 @@ An example configuration file (with all rules disabled):

```json
{
"rules": {
"alt-require": false,
"attr-lowercase": false,
"attr-no-duplication": false,
"attr-no-unnecessary-whitespace": false,
"attr-sorted": false,
"attr-unsafe-chars": false,
"attr-value-double-quotes": false,
"attr-value-no-duplication": false,
"attr-value-not-empty": false,
"attr-value-single-quotes": false,
"attr-whitespace": false,
"button-type-require": false,
"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,
"href-abs-or-rel": false,
"html-lang-require": false,
"id-class-ad-disabled": false,
"id-class-value": false,
"id-unique": false,
"inline-script-disabled": false,
"inline-style-disabled": false,
"input-requires-label": false,
"link-rel-canonical-require": false,
"main-require": false,
"meta-charset-require": false,
"meta-description-require": false,
"meta-viewport-require": false,
"script-disabled": false,
"space-tab-mixed-disabled": false,
"spec-char-escape": false,
"src-not-empty": false,
"style-disabled": false,
"tag-no-obsolete": false,
"tag-pair": false,
"tag-self-close": false,
"tagname-lowercase": false,
"tagname-specialchars": false,
"tags-check": false,
"title-require": false
}
"alt-require": false,
"attr-lowercase": false,
"attr-no-duplication": false,
"attr-no-unnecessary-whitespace": false,
"attr-sorted": false,
"attr-unsafe-chars": false,
"attr-value-double-quotes": false,
"attr-value-no-duplication": false,
"attr-value-not-empty": false,
"attr-value-single-quotes": false,
"attr-whitespace": false,
"button-type-require": false,
"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,
"href-abs-or-rel": false,
"html-lang-require": false,
"id-class-ad-disabled": false,
"id-class-value": false,
"id-unique": false,
"inline-script-disabled": false,
"inline-style-disabled": false,
"input-requires-label": false,
"link-rel-canonical-require": false,
"main-require": false,
"meta-charset-require": false,
"meta-description-require": false,
"meta-viewport-require": false,
"script-disabled": false,
"space-tab-mixed-disabled": false,
"spec-char-escape": false,
"src-not-empty": false,
"style-disabled": false,
"tag-no-obsolete": false,
"tag-pair": false,
"tag-self-close": false,
"tagname-lowercase": false,
"tagname-specialchars": false,
"tags-check": false,
"title-require": false
}
```

Expand Down
4 changes: 4 additions & 0 deletions website/src/content/docs/rules/empty-tag-not-self-closed.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,7 @@ Level: <Badge text="Warning" variant="caution" />
```html
<br />
```

:::note
This rule is incompatible with Prettier. If you use Prettier, you should disable this rule.
:::
2 changes: 2 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 @@ -4,6 +4,8 @@ title: frame-title-require
description: Requires that frame and iframe elements have an accessible name for screen readers and assistive technologies.
sidebar:
badge: New
keywords:
- accessibility
---

import { Badge } from '@astrojs/starlight/components';
Expand Down
2 changes: 2 additions & 0 deletions website/src/content/docs/rules/h1-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
id: h1-require
title: h1-require
description: Ensures that an HTML document contains at least one `<h1>` element for proper document structure and accessibility.
keywords:
- accessibility
---

import { Badge } from '@astrojs/starlight/components';
Expand Down
2 changes: 2 additions & 0 deletions website/src/content/docs/rules/html-lang-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ title: html-lang-require
description: Requires the lang attribute on the <html> element to ensure proper language declaration for accessibility and SEO.
keywords:
- i18n
- accessibility
- SEO
---

import { Badge } from '@astrojs/starlight/components';
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 @@ -2,6 +2,8 @@
id: main-require
title: main-require
description: Ensures that an HTML document contains a `<main>` element within the `<body>` tag for proper document structure and accessibility.
keywords:
- accessibility
---

import { Badge } from '@astrojs/starlight/components';
Expand Down
3 changes: 3 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 @@ -4,6 +4,9 @@ title: meta-description-require
description: Ensures every HTML document includes a non-blank meta description tag within the head element for better SEO.
sidebar:
badge: New
keywords:
- accessibility
- SEO
---

import { Badge } from '@astrojs/starlight/components';
Expand Down
2 changes: 2 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 @@ -4,6 +4,8 @@ title: meta-viewport-require
description: Ensures every HTML document includes a meta viewport tag within the head element for proper responsive design.
sidebar:
badge: New
keywords:
- accessibility
---

import { Badge } from '@astrojs/starlight/components';
Expand Down
5 changes: 5 additions & 0 deletions website/src/content/docs/rules/tagname-lowercase.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,8 @@ Level: <Badge text="Error" variant="danger" />
```html
<SPAN><BR>
```

### Why this rule is important

Lowercase tagnames typically have higher compression rates compared to uppercase tagnames allowing for slightly faster page loads.
Lowercase tagnames are also more readable and easier to understand.
Comment on lines +33 to +34
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The explanation for this rule's importance could be phrased more clearly and professionally. The current version has a minor grammatical awkwardness and could better articulate the benefits.

Lowercase tagnames typically have higher compression rates compared to uppercase tagnames, leading to slightly faster page loads.
Lowercase tagnames are also more readable and align with common coding conventions.

6 changes: 6 additions & 0 deletions website/src/content/docs/rules/tagname-specialchars.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,3 +27,9 @@ Level: <Badge text="Error" variant="danger" />
<@ href="link"></@>
<$pan>aab</$pan>
```

### Why this rule is important

Tagnames should only contain allowed characters to ensure consistency and readability.

Further reading: [HTML5 Specification - Tag names](https://html.spec.whatwg.org/multipage/syntax.html#syntax-tag-name)
3 changes: 3 additions & 0 deletions website/src/content/docs/rules/title-require.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
id: title-require
title: title-require
description: Ensures every HTML document includes a <title> tag within the <head> for accessibility and SEO.
keywords:
- accessibility
- SEO
---

import { Badge } from '@astrojs/starlight/components';
Expand Down
2 changes: 1 addition & 1 deletion website/src/content/docs/vs-code-extension.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import { LinkCard, CardGrid } from '@astrojs/starlight/components'

Get realtime linting feedback in Visual Studio Code with the HTMLHint extension. This extension provides a seamless integration of HTMLHint into your development workflow, allowing you to catch HTML issues as you type.

The HTMLHint extension will attempt to use the locally installed HTMLHint module (the project-specific module if present, or a globally installed HTMLHint module). If a locally installed HTMLHint isn't available, the extension will use the embedded version (current version 1.6.3).
The HTMLHint extension will attempt to use the locally installed HTMLHint module (the project-specific module if present, or a globally installed HTMLHint module). If a locally installed HTMLHint isn't available, the extension will use the embedded version (current version 1.7.0).

## Download

Expand Down
Loading