docs: improve rule docs

yeonjuan · Nov 25, 2023 · 433884a · 433884a
1 parent fc97b0d
commit 433884a
Show file tree

Hide file tree

Showing 40 changed files with 274 additions and 296 deletions.
diff --git a/docs/rules/element-newline.md b/docs/rules/element-newline.md
@@ -1,12 +1,10 @@
-# @html-eslint/element-newline
+# element-newline
 
-Enforce newline between elements.
+This rule enforces newlines between tags.
 
 ## How to use
 
-- .eslintrc.js
-
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/element-newline": "error",
@@ -16,8 +14,6 @@ module.exports = {
 
 ## Rule Details
 
-This rule enforces newline between elements.
-
 Examples of **incorrect** code for this rule:
 
 <!-- prettier-ignore -->
@@ -39,9 +35,21 @@ Examples of **correct** code for this rule:
 
 ### Options
 
-This rule has an object option.
+This rule has an object option:
+
+- `"skip"`: skips newline checking for the specified element's children.
+
+```ts
+//...
+"@html-eslint/element-newline": ["error", {
+  "skip": Array<string>
+}]
+```
 
-- `skip`: Specifies an array of tag names. Newlines are not checked for children elements of the specified tags.
+#### skip
+
+You can specify list of tag names in the `skip` option.
+Newline checking is not performed on children of the specified tags.
 
 Examples of **correct** code for the `{ "skip": ["pre", "code"] }` option:
 
@@ -50,8 +58,11 @@ Examples of **correct** code for the `{ "skip": ["pre", "code"] }` option:
 <pre>
     <div></div><div></div>
 </pre>
+```
 
+<!-- prettier-ignore -->
+```html
 <code>
-  <span></span><div></div>
+    <span></span><div></div>
 </code>
 ```
diff --git a/docs/rules/id-naming-convention.md b/docs/rules/id-naming-convention.md
@@ -1,12 +1,10 @@
-# @html-eslint/id-naming-convention
+# id-naming-convention
 
-- Enforce naming conventions for id attributes.
+This rule enforces consistent naming convention for `id` attribute values.
 
 ## How to use
 
-.eslintrc.js
-
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/id-naming-convention": "error",
@@ -16,8 +14,7 @@ module.exports = {
 
 ## Rule Details
 
-This rule enforces naming conventions for id attributes.
-It supports 4 naming cases. `camelCase`, `snake_case`, `PascalCase`, `kebab-case` (default `snake_case`).
+This rule supports 4 naming cases. `camelCase`, `snake_case`, `PascalCase`, `kebab-case` (default `snake_case`).
 
 ### Options
 
@@ -82,6 +79,6 @@ Examples of **correct** code for this rule with the `"kebab-case"` option:
 <div id="foo-bar"></div>
 ```
 
-## Further reading
+## Further Reading
 
 [Wiki - Naming convention](<https://en.wikipedia.org/wiki/Naming_convention_(programming)>)
diff --git a/docs/rules/indent.md b/docs/rules/indent.md
@@ -1,12 +1,10 @@
-# @html-eslint/indent
+# indent
 
-Enforce consistent indentation.
+This rule enforces consistent indentation.
 
 ## How to use
 
-- .eslintrc.js
-
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/indent": "error",
@@ -16,11 +14,14 @@ module.exports = {
 
 ## Rule Details
 
-This rule enforces consistent indentation styles. The default indent is `4 spaces`.
-
 ### Options
 
-This rule has two options
+```ts
+//...
+"@html-eslint/indent": ["error", "tab" | number]
+```
+
+This rule has two options.
 
 - `number(0, 1, ..)` (default 4): requires the use of indentation with specified number of spaces.
 
@@ -42,7 +43,7 @@ Examples of **correct** code for this rule:
 </html>
 ```
 
-#### space
+#### number (default: 4)
 
 If the option is number it means the number of spaces for indentation.
 
@@ -54,9 +55,10 @@ If the option is number it means the number of spaces for indentation.
 
 Examples of **incorrect** code for this rule with the `"2"` option:
 
+<!-- prettier-ignore -->
 ```html
 <html>
-  <body></body>
+      <body></body>
 </html>
 ```
 
@@ -68,8 +70,6 @@ Examples of **correct** code for this rule with the `"2"` option:
 </html>
 ```
 
-<!-- prettier-ignore-end -->
-
 #### tab
 
 If the option is `"tab"` it means using `tab` for indentation.
@@ -82,19 +82,17 @@ If the option is `"tab"` it means using `tab` for indentation.
 
 Examples of **incorrect** code for this rule:
 
+<!-- prettier-ignore -->
 ```html
 <html>
-  <body></body>
+          <body></body>
 </html>
 ```
 
 Examples of **correct** code for this rule:
 
 ```html
 <html>
-  <body>
-    <!-- tab -->
-  </body>
-  <!-- tab -->
+  <body></body>
 </html>
 ```
diff --git a/docs/rules/lowercase.md b/docs/rules/lowercase.md
@@ -1,17 +1,10 @@
----
-id: lowercase
-title: "lowercase"
----
-
 # lowercase
 
-Enforce to use lowercase for tag and attribute names.
+This rule enforces to use lowercase for tag and attribute names.
 
 ## How to use
 
-.eslintrc.js
-
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/lowercase": "error",

diff --git a/docs/rules/no-abstract-roles.md b/docs/rules/no-abstract-roles.md
@@ -1,10 +1,10 @@
-# @html-eslint/no-abstract-roles
+# no-abstract-roles
 
-Disallow use of abstract roles.
+This rule disallows use of abstract roles.
 
-- .eslintrc.js
+## How to use
 
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/no-abstract-roles": "error",
@@ -44,6 +44,6 @@ Examples of **correct** code for this rule:
 <div role="button"></div>
 ```
 
-## Further reading
+## Further Reading
 
 - [HTML spec - Abstract Roles](https://www.w3.org/TR/wai-aria-1.0/roles#abstract_roles)
diff --git a/docs/rules/no-accesskey-attrs.md b/docs/rules/no-accesskey-attrs.md
@@ -1,14 +1,15 @@
-# @html-eslint/no-accesskey-attrs
+# no-accesskey-attrs
 
-Disallow accesskey attributes.
+This rule disallows use of `accesskey` attributes.
 
-Access keys are HTML attributes that allow web developers to assign keyboard shortcuts to elements. Inconsistencies between keyboard shortcuts and keyboard commands used by screenreader and keyboard only users create accessibility complications so to avoid complications, access keys should not be used.
+## Why?
 
-## How to use
+`accesskey` attributes allow web developers to assign keyboard shortcuts to elements.
+Inconsistencies between keyboard shortcuts and keyboard commands used by screenreader and keyboard only users create accessibility complications so to avoid complications, access keys should not be used.
 
-- .eslintrc.js
+## How to use
 
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/no-accesskey-attrs": "error",
@@ -18,8 +19,6 @@ module.exports = {
 
 ## Rule Details
 
-This rule disallows the use of `accesskey` attributes.
-
 Examples of **incorrect** code for this rule:
 
 ```html
@@ -32,6 +31,6 @@ Examples of **correct** code for this rule:
 <div></div>
 ```
 
-## Further reading
+## Further Reading
 
-- [MDN - accesskey](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey)
+- [MDN: accesskey](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey)
diff --git a/docs/rules/no-aria-hidden-body.md b/docs/rules/no-aria-hidden-body.md
@@ -1,12 +1,17 @@
-# @html-eslint/no-aria-hidden-body
+# no-aria-hidden-body
 
-Disallow to use aria-hidden attributes on the `body` element.
+This rule disallows the use of `aria-hidden` attribute on the `body`.
 
-## How to use
+## Why?
+
+The `aria-hidden` attribute is typically used to hide elements from assistive technologies (such as screen readers) when they are not intended to be perceived by users.
 
-- .eslintrc.js
+When `aria-hidden`="true" is applied to the `<body>` element, it removes the entire content of the document from the accessibility tree.
+This means that assistive technologies will not perceive any of the content within the `<body>`, making the entire page inaccessible to users who rely on screen readers or other assistive technologies.
 
-```js
+## How to use
+
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/no-aria-hidden-body": "error",
@@ -16,8 +21,6 @@ module.exports = {
 
 ## Rule Details
 
-This rule disallows the use of aria-hidden attributes on the `body` element.
-
 Examples of **incorrect** code for this rule:
 
 ```html
@@ -32,6 +35,6 @@ Examples of **correct** code for this rule:
 <body></body>
 ```
 
-## Further reading
+## Further Reading
 
-- [MDN - Using the aria-hidden attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute)
+- [MDN: Using the aria-hidden attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute)
diff --git a/docs/rules/no-duplicate-attrs.md b/docs/rules/no-duplicate-attrs.md
@@ -1,12 +1,15 @@
-# @html-eslint/no-duplicate-attrs
+# no-duplicate-attrs
 
 Disallow duplicate attributes.
 
-## How to use
+## Why?
+
+The HTML specification mandates that attribute names must be unique within a single HTML element.
+Violating this rule results in non-compliance with the standard.
 
-- .eslintrc.js
+## How to use
 
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/no-duplicate-attrs": "error",

diff --git a/docs/rules/no-duplicate-id.md b/docs/rules/no-duplicate-id.md
@@ -1,12 +1,10 @@
-# @html-eslint/no-duplicate-id
+# no-duplicate-id
 
-Disallow duplicate `id` attributes.
+This rule disallows duplicate `id` attributes.
 
 ## How to use
 
-- .eslintrc.js
-
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/no-duplicate-id": "error",
@@ -16,8 +14,6 @@ module.exports = {
 
 ## Rule Details
 
-This rule disallow the use of duplicate `id` attributes.
-
 Examples of **incorrect** code for this rule:
 
 ```html
@@ -32,6 +28,6 @@ Examples of **correct** code for this rule:
 <div id="bar"></div>
 ```
 
-## Further reading
+## Further Reading
 
-- [MDN - id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)
+- [MDN: id](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)
diff --git a/docs/rules/no-extra-spacing-attrs.md b/docs/rules/no-extra-spacing-attrs.md
@@ -1,12 +1,10 @@
-# @html-eslint/no-extra-spacing-attrs
+# no-extra-spacing-attrs
 
-Disallow extra spaces around attributes.
+This rule disallows extra spaces around attributes.
 
 ## How to use
 
-- .eslintrc.js
-
-```js
+```js,.eslintrc.js
 module.exports = {
   rules: {
     "@html-eslint/no-extra-spacing-attrs": "error",
@@ -16,8 +14,6 @@ module.exports = {
 
 ## Rule Details
 
-This rule disallows the use of extra spaces around attributes.
-
 Examples of **incorrect** code for this rule:
 
 <!-- prettier-ignore -->