From 89ac0f7b1453962b158b0d95e150f05394708156 Mon Sep 17 00:00:00 2001 From: Kate Higa Date: Fri, 23 Dec 2022 10:41:58 -0500 Subject: [PATCH 1/7] Update library structure --- index.js | 9 +++------ {helpers => src/helpers}/strip-and-downcase-text.js | 0 src/rules/index.js | 3 +++ .../rules/no-default-alt-text.js | 0 .../rules/no-generic-link-text.js | 2 +- test/no-default-alt-text.test.js | 2 +- test/no-generic-link-text.test.js | 2 +- test/{helpers => }/strip-and-downcase-text.test.js | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) rename {helpers => src/helpers}/strip-and-downcase-text.js (100%) create mode 100644 src/rules/index.js rename no-default-alt-text.js => src/rules/no-default-alt-text.js (100%) rename no-generic-link-text.js => src/rules/no-generic-link-text.js (94%) rename test/{helpers => }/strip-and-downcase-text.test.js (91%) diff --git a/index.js b/index.js index c00a98e..c16a4ff 100644 --- a/index.js +++ b/index.js @@ -2,14 +2,11 @@ const _ = require("lodash"); const accessibilityRules = require("./style/accessibility.json"); const base = require("./style/base.json"); -const noDefaultAltText = require("./no-default-alt-text"); -const noGenericLinkText = require("./no-generic-link-text"); +const gitHubCustomRules = require("./src/rules/index").rules; -const customRules = [noDefaultAltText, noGenericLinkText]; +module.exports = [...gitHubCustomRules]; -module.exports = [...customRules]; - -for (const rule of customRules) { +for (const rule of gitHubCustomRules) { base[rule.names[1]] = true; } diff --git a/helpers/strip-and-downcase-text.js b/src/helpers/strip-and-downcase-text.js similarity index 100% rename from helpers/strip-and-downcase-text.js rename to src/helpers/strip-and-downcase-text.js diff --git a/src/rules/index.js b/src/rules/index.js new file mode 100644 index 0000000..c6c9664 --- /dev/null +++ b/src/rules/index.js @@ -0,0 +1,3 @@ +module.exports = { + rules: [require("./no-default-alt-text"), require("./no-generic-link-text")], +}; diff --git a/no-default-alt-text.js b/src/rules/no-default-alt-text.js similarity index 100% rename from no-default-alt-text.js rename to src/rules/no-default-alt-text.js diff --git a/no-generic-link-text.js b/src/rules/no-generic-link-text.js similarity index 94% rename from no-generic-link-text.js rename to src/rules/no-generic-link-text.js index c16cd67..b88b512 100644 --- a/no-generic-link-text.js +++ b/src/rules/no-generic-link-text.js @@ -1,4 +1,4 @@ -const { stripAndDowncaseText } = require("./helpers/strip-and-downcase-text"); +const { stripAndDowncaseText } = require("../helpers/strip-and-downcase-text"); const bannedLinkText = [ "read more", diff --git a/test/no-default-alt-text.test.js b/test/no-default-alt-text.test.js index 5032250..a5c1976 100644 --- a/test/no-default-alt-text.test.js +++ b/test/no-default-alt-text.test.js @@ -1,4 +1,4 @@ -const altTextRule = require("../no-default-alt-text"); +const altTextRule = require("../src/rules/no-default-alt-text"); const runTest = require("./utils/run-test").runTest; describe("GH001: No Default Alt Text", () => { diff --git a/test/no-generic-link-text.test.js b/test/no-generic-link-text.test.js index f51a1db..174207d 100644 --- a/test/no-generic-link-text.test.js +++ b/test/no-generic-link-text.test.js @@ -1,4 +1,4 @@ -const noGenericLinkTextRule = require("../no-generic-link-text"); +const noGenericLinkTextRule = require("../src/rules/no-generic-link-text"); const runTest = require("./utils/run-test").runTest; describe("GH002: No Generic Link Text", () => { diff --git a/test/helpers/strip-and-downcase-text.test.js b/test/strip-and-downcase-text.test.js similarity index 91% rename from test/helpers/strip-and-downcase-text.test.js rename to test/strip-and-downcase-text.test.js index 2617b25..9357a3c 100644 --- a/test/helpers/strip-and-downcase-text.test.js +++ b/test/strip-and-downcase-text.test.js @@ -1,6 +1,6 @@ const { stripAndDowncaseText, -} = require("../../helpers/strip-and-downcase-text"); +} = require("../src/helpers/strip-and-downcase-text"); describe("stripAndDowncaseText", () => { test("strips extra whitespace", () => { From e8fc30d3bd62118acda5a71f985979f500a251aa Mon Sep 17 00:00:00 2001 From: Kate Higa Date: Fri, 23 Dec 2022 11:31:38 -0500 Subject: [PATCH 2/7] Add docs folder --- README.md | 4 +- docs/rules/GH001-no-default-alt-text.md | 37 ++++++++++++++++ docs/rules/GH002-no-generic-link-text.md | 54 ++++++++++++++++++++++++ package.json | 2 +- 4 files changed, 94 insertions(+), 3 deletions(-) create mode 100644 docs/rules/GH001-no-default-alt-text.md create mode 100644 docs/rules/GH002-no-generic-link-text.md diff --git a/README.md b/README.md index b2b6d86..b9d1a8d 100644 --- a/README.md +++ b/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`. diff --git a/docs/rules/GH001-no-default-alt-text.md b/docs/rules/GH001-no-default-alt-text.md new file mode 100644 index 0000000..0c9a54c --- /dev/null +++ b/docs/rules/GH001-no-default-alt-text.md @@ -0,0 +1,37 @@ +# 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. + +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 +Screen Shot 2022-06-26 at 7 41 30 PM +``` + +### Correct 👍 + +```md +![](https://user-images.githubusercontent.com/abcdef.png) +``` + +```md +A fluffy, orange kitten plays with a ball of yarn +``` + +```md + +A GitHub Discussion page with the heading structure visually surfaced with a text overlay +``` + diff --git a/docs/rules/GH002-no-generic-link-text.md b/docs/rules/GH002-no-generic-link-text.md new file mode 100644 index 0000000..9637f1c --- /dev/null +++ b/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 is too generic, it becomes difficult to quickly identify the destination of the link. + +Ensure that your link text is descriptive and the purpose of the link is clear even when read out of context of 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) +``` \ No newline at end of file diff --git a/package.json b/package.json index f768e82..b0b3cf4 100644 --- a/package.json +++ b/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": { From 3d9e55cb3d947a5e74cae5779e3af60279f7561d Mon Sep 17 00:00:00 2001 From: Kate Higa Date: Fri, 23 Dec 2022 11:35:10 -0500 Subject: [PATCH 3/7] Update information link --- src/rules/no-default-alt-text.js | 2 +- src/rules/no-generic-link-text.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/rules/no-default-alt-text.js b/src/rules/no-default-alt-text.js index 4e15c32..da0bdd6 100644 --- a/src/rules/no-default-alt-text.js +++ b/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) { diff --git a/src/rules/no-generic-link-text.js b/src/rules/no-generic-link-text.js index b88b512..278cc8e 100644 --- a/src/rules/no-generic-link-text.js +++ b/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) { From fcd460b381bbbb814855940b68222e1709b45265 Mon Sep 17 00:00:00 2001 From: Kate Higa <16447748+khiga8@users.noreply.github.com> Date: Wed, 28 Dec 2022 10:01:15 -0500 Subject: [PATCH 4/7] Update docs/rules/GH002-no-generic-link-text.md Co-authored-by: Joyce Zhu --- docs/rules/GH002-no-generic-link-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/GH002-no-generic-link-text.md b/docs/rules/GH002-no-generic-link-text.md index 9637f1c..1fdd57d 100644 --- a/docs/rules/GH002-no-generic-link-text.md +++ b/docs/rules/GH002-no-generic-link-text.md @@ -4,7 +4,7 @@ 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 is too generic, it becomes difficult to quickly identify the destination of the link. +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 out of context of surrounding text. From d69622f99f89b66d88032ef10a642878759912ae Mon Sep 17 00:00:00 2001 From: Kate Higa <16447748+khiga8@users.noreply.github.com> Date: Wed, 28 Dec 2022 10:01:22 -0500 Subject: [PATCH 5/7] Update docs/rules/GH002-no-generic-link-text.md Co-authored-by: Joyce Zhu --- docs/rules/GH002-no-generic-link-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/GH002-no-generic-link-text.md b/docs/rules/GH002-no-generic-link-text.md index 1fdd57d..4ed3ca6 100644 --- a/docs/rules/GH002-no-generic-link-text.md +++ b/docs/rules/GH002-no-generic-link-text.md @@ -6,7 +6,7 @@ Avoid setting generic link text like, "Click here", "Read more", and "Learn more 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 out of context of surrounding text. +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). From 98c098313bff39e0507d028ec42c430f468ce552 Mon Sep 17 00:00:00 2001 From: Kate Higa <16447748+khiga8@users.noreply.github.com> Date: Wed, 28 Dec 2022 10:03:26 -0500 Subject: [PATCH 6/7] Update GH001-no-default-alt-text.md --- docs/rules/GH001-no-default-alt-text.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/rules/GH001-no-default-alt-text.md b/docs/rules/GH001-no-default-alt-text.md index 0c9a54c..13e7ab5 100644 --- a/docs/rules/GH001-no-default-alt-text.md +++ b/docs/rules/GH001-no-default-alt-text.md @@ -23,7 +23,9 @@ Learn more at [Primer: Alternative text for images](https://primer.style/design/ ### Correct 👍 ```md -![](https://user-images.githubusercontent.com/abcdef.png) + + +![""](https://user-images.githubusercontent.com/abcdef.png) ``` ```md @@ -31,7 +33,6 @@ Learn more at [Primer: Alternative text for images](https://primer.style/design/ ``` ```md - A GitHub Discussion page with the heading structure visually surfaced with a text overlay ``` From bd8b98485a740aa76522816caaf2e0ce10329b88 Mon Sep 17 00:00:00 2001 From: Kate Higa <16447748+khiga8@users.noreply.github.com> Date: Wed, 28 Dec 2022 13:24:13 -0500 Subject: [PATCH 7/7] Update docs/rules/GH001-no-default-alt-text.md Co-authored-by: Eric Bailey --- docs/rules/GH001-no-default-alt-text.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/rules/GH001-no-default-alt-text.md b/docs/rules/GH001-no-default-alt-text.md index 13e7ab5..132cbdc 100644 --- a/docs/rules/GH001-no-default-alt-text.md +++ b/docs/rules/GH001-no-default-alt-text.md @@ -4,7 +4,7 @@ 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. +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).