Introduce rule documentation (#26)

* Update library structure

* Add docs folder

* Update information link

* Update docs/rules/GH002-no-generic-link-text.md

Co-authored-by: Joyce Zhu <joycezhu@github.com>

* Update docs/rules/GH002-no-generic-link-text.md

Co-authored-by: Joyce Zhu <joycezhu@github.com>

* Update GH001-no-default-alt-text.md

* Update docs/rules/GH001-no-default-alt-text.md

Co-authored-by: Eric Bailey <ericwbailey@users.noreply.github.com>

Co-authored-by: Joyce Zhu <joycezhu@github.com>
Co-authored-by: Eric Bailey <ericwbailey@users.noreply.github.com>

Author: 3 people

README.md

@@ -22,8 +22,8 @@ However, others of these rules should **NOT** be disabled because they encourage
 
 The following are custom rules defined in this plugin.
 
-- **GH001** _no-default-alt-text_
-- **GH002** _no-generic-link-text_
+- [**GH001** _no-default-alt-text_](./docs/rules/GH001-no-default-alt-text.md)
+- [**GH002** _no-generic-link-text_](./docs/rules/GH002-no-generic-link-text.md)
 
 See [`markdownlint` rules](https://github.com/DavidAnson/markdownlint#rules--aliases) for documentation on rules pulled in from `markdownlint`.
 

docs/rules/GH001-no-default-alt-text.md

@@ -0,0 +1,38 @@
+# GH001 No default alt text
+
+## Rule details
+
+Images should not use the macOS default screenshot filename as alternate text (alt text) which does not convey any meaningful information.
+
+Alternative text should concisely describe what is conveyed in the image. If the image is decorative, the alternative text should be set to an empty string (`alt=""`).
+
+Learn more at [Primer: Alternative text for images](https://primer.style/design/accessibility/alternative-text-for-images).
+
+## Examples
+
+### Incorrect 👎
+
+```md
+![Screen Shot 2022-06-26 at 7 41 30 PM](https://user-images.githubusercontent.com/abcdef.png)
+```
+
+```md
+<img alt="Screen Shot 2022-06-26 at 7 41 30 PM" src="https://user-images.githubusercontent.com/abcdef.png">
+```
+
+### Correct 👍
+
+```md
+<!-- Mark decorative images with an empty string -->
+
+![""](https://user-images.githubusercontent.com/abcdef.png)
+```
+
+```md
+<img alt="A fluffy, orange kitten plays with a ball of yarn" src="https://user-images.githubusercontent.com/defgh.png">
+```
+
+```md
+<img alt="A GitHub Discussion page with the heading structure visually surfaced with a text overlay" src="https://user-images.githubusercontent.com/xyz.png">
+```
+

docs/rules/GH002-no-generic-link-text.md

@@ -0,0 +1,54 @@
+# GH002 No generic link text
+
+## Rule details
+
+Avoid setting generic link text like, "Click here", "Read more", and "Learn more" which do not make sense when read out of context.
+
+Screen reader users often tab through links on a page to quickly find content without needing to listen to the full page. When link text does not clearly describe the actual linked content, it becomes difficult to quickly identify whether it's worth following the link.
+
+Ensure that your link text is descriptive and the purpose of the link is clear even when read without the context provided by surrounding text.
+
+Learn more about how to write descriptive link text at [Access Guide: Write descriptive link text](https://www.accessguide.io/guide/descriptive-link-text).
+
+**Note**: For now, this rule only flags inline markdown implementation of links given the complexities of determining the accessible name of an HTML anchor tag,
+
+## Configuration
+
+You can configure additional link texts to flag by setting the rule configuration like the following:
+
+```.js
+{
+    "no-generic-link-text": {
+        "additional_banned_texts": ["Something", "Go here"]
+    }
+}
+```
+## Examples
+
+### Incorrect 👎
+
+```md
+Go [here](https://github.com/)
+```
+
+```md
+[Learn more](https://docs.github.com)
+```
+
+```md
+[Click here](https://github.com/new) to create a new repository.
+```
+
+### Correct 👍
+
+```md
+[GitHub](https://github.com/)
+```
+
+```md
+[GitHub Docs](https://docs.github.com)
+```
+
+```md
+[Create a new repository](https://github.com/new) 
+```

package.json

@@ -9,7 +9,7 @@
   "scripts": {
     "publish": "npm publish --access public --@github:registry=https://registry.npmjs.org",
     "test": "npm run lint && jest",
-    "lint": "markdownlint-cli2 \"**/*.{md,mdx}\" \"!node_modules\"  \"!test/example.md\" && eslint .",
+    "lint": "markdownlint-cli2 \"**/*.{md,mdx}\" \"!node_modules\" \"!docs/rules\" \"!test/example.md\" && eslint .",
     "lint:fix": "npm run lint -- --fix"
   },
   "dependencies": {

src/rules/no-default-alt-text.js

@@ -11,7 +11,7 @@ module.exports = {
   description:
     "Images should not use the MacOS default screenshot filename as alternate text (alt text). If you have not changed this file, try merging main with your branch. For more information see: https://primer.style/design/accessibility/alternative-text-for-images",
   information: new URL(
-    "https://primer.style/design/accessibility/alternative-text-for-images"
+    "https://github.com/github/markdownlint-github/blob/main/docs/rules/GH001-no-default-alt-text.md"
   ),
   tags: ["accessibility", "images"],
   function: function GH001(params, onError) {

src/rules/no-generic-link-text.js

@@ -14,7 +14,7 @@ module.exports = {
   description:
     "Avoid using generic link text like `Learn more` or `Click here`",
   information: new URL(
-    "https://primer.style/design/accessibility/links#writing-link-text"
+    "https://github.com/github/markdownlint-github/blob/main/docs/rules/GH002-no-generic-link-text.md"
   ),
   tags: ["accessibility", "links"],
   function: function GH002(params, onError) {