docs: automate docs with eslint-doc-generator

jsx-eslint · Oct 27, 2022 · c804098 · c804098
1 parent 0a73cf4
commit c804098
Show file tree

Hide file tree

Showing 67 changed files with 236 additions and 248 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -28,20 +28,6 @@
         "eslint-plugin/require-meta-type": "off",
       },
     },
-    {
-      "files": ["markdown.config.js"],
-      "parserOptions": {
-        "sourceType": "script",
-      },
-      "rules": {
-        "no-console": 0,
-        "import/no-extraneous-dependencies":  [
-           "error",
-           { "devDependencies": true },
-        ],
-        "strict": ["error", "global"],
-      },
-    },
     {
       "files": ["__tests__/src/rules/*.js"],
       "extends": ["plugin:eslint-plugin/tests-recommended"],

diff --git a/.github/workflows/readme.yml b/.github/workflows/readme.yml
@@ -12,4 +12,5 @@ jobs:
         name: 'nvm install lts/* && npm install'
         with:
           node-version: 'lts/*'
+      - run: npm run build
       - run: npm run generate-list-of-rules:check
diff --git a/README.md b/README.md
diff --git a/docs/rules/accessible-emoji.md b/docs/rules/accessible-emoji.md
@@ -1,4 +1,8 @@
-# [Deprecated] accessible-emoji
+# accessible-emoji
+
+❌ This rule is deprecated.
+
+<!-- end auto-generated rule header -->
 
 Emoji have become a common way of communicating content to the end user. To a person using a screenreader, however, they may not be aware that this content is there at all. By wrapping the emoji in a `<span>`, giving it the `role="img"`, and providing a useful description in `aria-label`, the screenreader will treat the emoji as an image in the accessibility tree with an accessible name for the end user.
 

diff --git a/docs/rules/alt-text.md b/docs/rules/alt-text.md
@@ -1,5 +1,9 @@
 # alt-text
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that all elements that require alternative text have meaningful information to relay back to the end user. This is a critical component of accessibility for screen reader users in order for them to understand the content's purpose on the page. By default, this rule checks for alternative text on the following elements: `<img>`, `<area>`, `<input type="image">`, and `<object>`.
 
 ## How to resolve

diff --git a/docs/rules/anchor-ambiguous-text.md b/docs/rules/anchor-ambiguous-text.md
@@ -1,5 +1,9 @@
 # anchor-ambiguous-text
 
+✅ This rule is _disabled_ in the `recommended` config.
+
+<!-- end auto-generated rule header -->
+
 Enforces `<a>` values are not exact matches for the phrases "click here", "here", "link", "a link", or "learn more". Screenreaders announce tags as links/interactive, but rely on values for context. Ambiguous anchor descriptions do not provide sufficient context for users.
 
 ## Rule details

diff --git a/docs/rules/anchor-has-content.md b/docs/rules/anchor-has-content.md
@@ -1,5 +1,9 @@
 # anchor-has-content
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that anchors have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
 
 ## Rule details

diff --git a/docs/rules/anchor-is-valid.md b/docs/rules/anchor-is-valid.md
@@ -1,5 +1,9 @@
 # anchor-is-valid
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 The HTML `<a>` element, with a valid `href` attribute, is formally defined as representing a **hyperlink**. That is, a link between one HTML document and another, or between one location inside an HTML document and another location inside the same document.
 
 In fact, the interactive, underlined `<a>` element has become so synonymous with web navigation that this expectation has become entrenched inside browsers, assistive technologies such as screen readers and in how people generally expect the internet to behave. In short, anchors should navigate.

diff --git a/docs/rules/aria-activedescendant-has-tabindex.md b/docs/rules/aria-activedescendant-has-tabindex.md
@@ -1,5 +1,9 @@
 # aria-activedescendant-has-tabindex
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 `aria-activedescendant` is used to manage focus within a [composite widget](https://www.w3.org/TR/wai-aria/#composite).
 The element with the attribute `aria-activedescendant` retains the active document
 focus; it indicates which of its child elements has secondary focus by assigning

diff --git a/docs/rules/aria-props.md b/docs/rules/aria-props.md
@@ -1,5 +1,9 @@
 # aria-props
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Elements cannot use an invalid ARIA attribute. This will fail if it finds an `aria-*` property that is not listed in [WAI-ARIA States and Properties spec](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties).
 
 ## Rule details

diff --git a/docs/rules/aria-proptypes.md b/docs/rules/aria-proptypes.md
@@ -1,5 +1,9 @@
 # aria-proptypes
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 ARIA state and property values must be valid.
 
 ## Rule details

diff --git a/docs/rules/aria-role.md b/docs/rules/aria-role.md
@@ -1,5 +1,9 @@
 # aria-role
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Elements with ARIA roles must use a valid, non-abstract ARIA role. A reference to role definitions can be found at [WAI-ARIA](https://www.w3.org/TR/wai-aria/#role_definitions) site.
 
 ## Rule details

diff --git a/docs/rules/aria-unsupported-elements.md b/docs/rules/aria-unsupported-elements.md
@@ -1,5 +1,9 @@
 # aria-unsupported-elements
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Certain reserved DOM elements do not support ARIA roles, states and properties. This is often because they are not visible, for example `meta`, `html`, `script`, `style`. This rule enforces that these DOM elements do not contain the `role` and/or `aria-*` props.
 
 ## Rule details

diff --git a/docs/rules/autocomplete-valid.md b/docs/rules/autocomplete-valid.md
@@ -1,5 +1,9 @@
 # autocomplete-valid
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Ensure the autocomplete attribute is correct and suitable for the form field it is used with.
 
 ## Rule details

diff --git a/docs/rules/click-events-have-key-events.md b/docs/rules/click-events-have-key-events.md
@@ -1,5 +1,9 @@
 # click-events-have-key-events
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce `onClick` is accompanied by at least one of the following: `onKeyUp`, `onKeyDown`, `onKeyPress`. Coding for the keyboard is important for users with physical disabilities who cannot use a mouse, AT compatibility, and screenreader users. This does not apply for interactive or hidden elements.
 
 ## Rule details

diff --git a/docs/rules/control-has-associated-label.md b/docs/rules/control-has-associated-label.md
@@ -1,5 +1,9 @@
 # control-has-associated-label
 
+💼 This rule is _disabled_ in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that a control (an interactive element) has a text label.
 
 There are two supported ways to supply a control with a text label:

diff --git a/docs/rules/heading-has-content.md b/docs/rules/heading-has-content.md
@@ -1,5 +1,9 @@
 # heading-has-content
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that heading elements (`h1`, `h2`, etc.) have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
 
 ## Rule details

diff --git a/docs/rules/html-has-lang.md b/docs/rules/html-has-lang.md
@@ -1,5 +1,9 @@
 # html-has-lang
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 <html> elements must have the lang prop. This rule is largely superseded by the [`lang` rule](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/lang.md).
 
 ## Rule details

diff --git a/docs/rules/iframe-has-title.md b/docs/rules/iframe-has-title.md
@@ -1,5 +1,9 @@
 # iframe-has-title
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 `<iframe>` elements must have a unique title property to indicate its content to the user.
 
 ## Rule details

diff --git a/docs/rules/img-redundant-alt.md b/docs/rules/img-redundant-alt.md
@@ -1,5 +1,9 @@
 # img-redundant-alt
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce img alt attribute does not contain the word image, picture, or photo. Screenreaders already announce `img` elements as an image. There is no need to use words such as *image*, *photo*, and/or *picture*.
 
 ## Rule details

diff --git a/docs/rules/interactive-supports-focus.md b/docs/rules/interactive-supports-focus.md
@@ -1,5 +1,9 @@
 # interactive-supports-focus
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Elements with an interactive role and interaction handlers (mouse or key press) must be focusable.
 
 ## How do I resolve this error?

diff --git a/docs/rules/label-has-associated-control.md b/docs/rules/label-has-associated-control.md
@@ -1,5 +1,9 @@
 # label-has-associated-control
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that a label tag has a text label and an associated control.
 
 There are two supported ways to associate a label with a control:

diff --git a/docs/rules/label-has-for.md b/docs/rules/label-has-for.md
@@ -1,4 +1,10 @@
-# [Deprecated] label-has-for
+# label-has-for
+
+❌ This rule is deprecated.
+
+💼 This rule is _disabled_ in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
 
 *This rule was deprecated in v6.1.0. It will no longer be maintained. Please use [`label-has-associated-control`](label-has-associated-control.md) instead.*
 

diff --git a/docs/rules/lang.md b/docs/rules/lang.md
@@ -1,5 +1,7 @@
 # lang
 
+<!-- end auto-generated rule header -->
+
 The `lang` prop on the `<html>` element must be a valid IETF's BCP 47 language tag.
 
 ## Rule details

diff --git a/docs/rules/media-has-caption.md b/docs/rules/media-has-caption.md
@@ -1,5 +1,9 @@
 # media-has-caption
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Providing captions for media is essential for deaf users to follow along. Captions should be a transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information. Not only is this important for accessibility, but can also be useful for all users in the case that the media is unavailable (similar to `alt` text on an image when an image is unable to load).
 
 The captions should contain all important and relevant information to understand the corresponding media. This may mean that the captions are not a 1:1 mapping of the dialogue in the media content. However, captions are *not* necessary for video components with the `muted` attribute.

diff --git a/docs/rules/mouse-events-have-key-events.md b/docs/rules/mouse-events-have-key-events.md
@@ -1,5 +1,9 @@
 # mouse-events-have-key-events
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce onmouseover/onmouseout are accompanied by onfocus/onblur. Coding for the keyboard is important for users with physical disabilities who cannot use a mouse, AT compatibility, and screenreader users.
 
 ## Rule details

diff --git a/docs/rules/no-access-key.md b/docs/rules/no-access-key.md
@@ -1,5 +1,9 @@
 # no-access-key
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce no accessKey prop on element. Access keys are HTML attributes that allow web developers to assign keyboard shortcuts to elements. Inconsistencies between keyboard shortcuts and keyboard commands used by screenreaders and keyboard-only users create accessibility complications so to avoid complications, access keys should not be used.
 
 ### References

diff --git a/docs/rules/no-autofocus.md b/docs/rules/no-autofocus.md
@@ -1,5 +1,9 @@
 # no-autofocus
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that autoFocus prop is not used on elements. Autofocusing elements can cause usability issues for sighted and non-sighted users, alike.
 
 ## Rule details

diff --git a/docs/rules/no-distracting-elements.md b/docs/rules/no-distracting-elements.md
@@ -1,5 +1,9 @@
 # no-distracting-elements
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforces that no distracting elements are used. Elements that can be visually distracting can cause accessibility issues with visually impaired users. Such elements are most likely deprecated, and should be avoided. By default, the following elements are visually distracting: `<marquee>` and `<blink>`.
 
 ## Rule details

diff --git a/docs/rules/no-interactive-element-to-noninteractive-role.md b/docs/rules/no-interactive-element-to-noninteractive-role.md
@@ -1,5 +1,9 @@
 # no-interactive-element-to-noninteractive-role
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Interactive HTML elements indicate _controls_ in the user interface. Interactive elements include `<a href>`, `<button>`, `<input>`, `<select>`, `<textarea>`.
 
 Non-interactive HTML elements and non-interactive ARIA roles indicate _content_ and _containers_ in the user interface. Non-interactive elements include `<main>`, `<area>`, `<h1>` (,`<h2>`, etc), `<img>`, `<li>`, `<ul>` and `<ol>`.

diff --git a/docs/rules/no-noninteractive-element-interactions.md b/docs/rules/no-noninteractive-element-interactions.md
@@ -1,5 +1,9 @@
 # no-noninteractive-element-interactions
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Non-interactive HTML elements and non-interactive ARIA roles indicate _content_ and _containers_ in the user interface. A non-interactive element does not support event handlers (mouse and key handlers). Non-interactive elements include `<main>`, `<area>`, `<h1>` (,`<h2>`, etc), `<p>`, `<img>`, `<li>`, `<ul>` and `<ol>`. Non-interactive [WAI-ARIA roles](https://www.w3.org/TR/wai-aria-1.1/#usage_intro) include `article`, `banner`, `complementary`, `img`, `listitem`, `main`, `region` and `tooltip`.
 
 ## How do I resolve this error?

diff --git a/docs/rules/no-noninteractive-element-to-interactive-role.md b/docs/rules/no-noninteractive-element-to-interactive-role.md
@@ -1,5 +1,9 @@
 # no-noninteractive-element-to-interactive-role
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Non-interactive HTML elements indicate _content_ and _containers_ in the user interface. Non-interactive elements include `<main>`, `<area>`, `<h1>` (,`<h2>`, etc), `<img>`, `<li>`, `<ul>` and `<ol>`.
 
 Interactive HTML elements indicate _controls_ in the user interface. Interactive elements include `<a href>`, `<button>`, `<input>`, `<select>`, `<textarea>`.

diff --git a/docs/rules/no-noninteractive-tabindex.md b/docs/rules/no-noninteractive-tabindex.md
@@ -1,5 +1,9 @@
 # no-noninteractive-tabindex
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Tab key navigation should be limited to elements on the page that can be interacted with. Thus it is not necessary to add a tabindex to items in an unordered list, for example, to make them navigable through assistive technology. These applications already afford page traversal mechanisms based on the HTML of the page. Generally, we should try to reduce the size of the page's tab ring rather than increasing it.
 
 ## How do I resolve this error?

diff --git a/docs/rules/no-onchange.md b/docs/rules/no-onchange.md
@@ -1,4 +1,8 @@
-# [Deprecated] no-onchange
+# no-onchange
+
+❌ This rule is deprecated.
+
+<!-- end auto-generated rule header -->
 
 ⚠️ **Deprecated:** This rule is based on reports of behavior of [old browsers (eg. IE 10 and below)](https://www.quirksmode.org/dom/events/change.html#t05). In the meantime, this behavior has been corrected, both in newer versions of browsers as well as [in the DOM spec](https://bugzilla.mozilla.org/show_bug.cgi?id=969068#c2).
 

diff --git a/docs/rules/no-redundant-roles.md b/docs/rules/no-redundant-roles.md
@@ -1,5 +1,9 @@
 # no-redundant-roles
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Some HTML elements have native semantics that are implemented by the browser. This includes default/implicit ARIA roles. Setting an ARIA role that matches its default/implicit role is redundant since it is already set by the browser.
 
 ## Rule details

diff --git a/docs/rules/no-static-element-interactions.md b/docs/rules/no-static-element-interactions.md
@@ -1,5 +1,9 @@
 # no-static-element-interactions
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Static HTML elements do not have semantic meaning. This is clear in the case of `<div>` and `<span>`. It is less so clear in the case of elements that _seem_ semantic, but that do not have a semantic mapping in the accessibility layer. For example `<a>`, `<big>`, `<blockquote>`, `<footer>`, `<picture>`, `<strike>` and `<time>` -- to name a few -- have no semantic layer mapping. They are as void of meaning as `<div>`.
 
 The [WAI-ARIA `role` attribute](https://www.w3.org/TR/wai-aria-1.1/#usage_intro) confers a semantic mapping to an element. The semantic value can then be expressed to a user via assistive technology.

diff --git a/docs/rules/prefer-tag-over-role.md b/docs/rules/prefer-tag-over-role.md
@@ -0,0 +1,5 @@
+# prefer-tag-over-role
+
+<!-- end auto-generated rule header -->
+
+TODO
diff --git a/docs/rules/role-has-required-aria-props.md b/docs/rules/role-has-required-aria-props.md
@@ -1,5 +1,9 @@
 # role-has-required-aria-props
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Elements with ARIA roles must have all required attributes for that role.
 
 ## Rule details

diff --git a/docs/rules/role-supports-aria-props.md b/docs/rules/role-supports-aria-props.md
@@ -1,5 +1,9 @@
 # role-supports-aria-props
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 Enforce that elements with explicit or implicit roles defined contain only `aria-*` properties supported by that `role`. Many ARIA attributes (states and properties) can only be used on elements with particular roles. Some elements have implicit roles, such as `<a href="#" />`, which will resolve to `role="link"`.
 
 ## Rule details

diff --git a/docs/rules/scope.md b/docs/rules/scope.md
@@ -1,5 +1,9 @@
 # scope
 
+💼 This rule is enabled in the following configs: ✅ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
 The `scope` prop should be used only on `<th>` elements.
 
 ## Rule details