github · khiga8 · Oct 9, 2023 · Oct 6, 2023 · Oct 6, 2023 · Oct 6, 2023
@@ -14,6 +14,7 @@ The following are custom rules defined in this plugin.

 * [**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)
+* [**GH002** _no-empty-alt-text_](./docs/rules/GH002-no-empty-alt-text.md)

 See [`markdownlint` rules](https://github.com/DavidAnson/markdownlint#rules--aliases) for documentation on rules pulled in from `markdownlint`.


@@ -0,0 +1,27 @@
+# GH003 No Empty Alt Text
+
+## Rule details
+
+⚠️ This rule is _off_ by default and is only applicable for GitHub rendered markdown.
+
+Currently, all images on github.com are automatically wrapped in an anchor tag.
+
+As a result, images that are intentionally marked as decorative (via `alt=""`) end up rendering as a link without an accessible name. This is confusing and inaccessible for assistive technology users. 
+
+This rule can be enabled to enforce that the alt attribute is always set to descriptive text. 
+
+This rule should be removed once this behavior is updated on GitHub's UI.
+
+## Examples
+
+### Incorrect 👎
+
+```html
+<img src="cat.png" alt="">
+```
+
+### Correct 👍
+
+```html
+<img src="mona.png" alt="Mona Lisa, the Octocat">
+```
@@ -6,8 +6,11 @@ const gitHubCustomRules = require("./src/rules/index").rules;

 module.exports = [...gitHubCustomRules];

+const offByDefault = ["no-empty-alt-text"];
+
 for (const rule of gitHubCustomRules) {
-  base[rule.names[1]] = true;
+  const ruleName = rule.names[1];
+  base[ruleName] = offByDefault.includes(ruleName) ? false : true;
 }

 module.exports.init = function init(consumerConfig) {

@@ -1,3 +1,7 @@
 module.exports = {
-  rules: [require("./no-default-alt-text"), require("./no-generic-link-text")],
+  rules: [
+    require("./no-default-alt-text"),
+    require("./no-generic-link-text"),
+    require("./no-empty-alt-text"),
+  ],
 };
@@ -23,7 +23,12 @@ module.exports = {
  function: function GH001(params, onError) {
    const htmlTagsWithImages = params.parsers.markdownit.tokens.filter(
      (token) => {
-        return token.type === "html_block" && token.content.includes("<img");
+        return (
+          (token.type === "html_block" && token.content.includes("<img")) ||
+          (token.type === "inline" &&
+            token.content.includes("<img") &&
+            token.children.some((child) => child.type === "html_inline"))
+        );
      },
    );
    const inlineImages = params.parsers.markdownit.tokens.filter(
@@ -36,12 +41,15 @@ module.exports = {
      const lineRange = token.map;
      const lineNumber = token.lineNumber;
      const lines = params.lines.slice(lineRange[0], lineRange[1]);
-
      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
        let matches;
        if (token.type === "inline") {
-          matches = line.matchAll(markdownAltRegex);
+          if (token.children.some((child) => child.type === "html_inline")) {
+            matches = line.matchAll(htmlAltRegex);
+          } else {
+            matches = line.matchAll(markdownAltRegex);
+          }
        } else {
          matches = line.matchAll(htmlAltRegex);
        }
@@ -51,6 +59,7 @@ module.exports = {
          onError({
            lineNumber: lineNumber + i,
            range: [startIndex + 1, altText.length],
+            detail: `Flagged alt: ${altText}`,
          });
        }
      }

@@ -0,0 +1,40 @@
+module.exports = {
+  names: ["GH003", "no-empty-alt-text"],
+  description: "Please provide an alternative text for the image.",
+  information: new URL(
+    "https://github.com/github/markdownlint-github/blob/main/docs/rules/GH003-no-empty-alt-text.md",
+  ),
+  tags: ["accessibility", "images"],
+  function: function GH003(params, onError) {
+    const htmlTagsWithImages = params.parsers.markdownit.tokens.filter(
+      (token) => {
+        return (
+          (token.type === "html_block" && token.content.includes("<img")) ||
+          (token.type === "inline" &&
+            token.content.includes("<img") &&
+            token.children.some((child) => child.type === "html_inline"))
+        );
+      },
+    );
+
+    const htmlAltRegex = new RegExp(/alt=['"]['"]/, "gid");
+
+    for (const token of htmlTagsWithImages) {
+      const lineRange = token.map;
+      const lineNumber = token.lineNumber;
+      const lines = params.lines.slice(lineRange[0], lineRange[1]);
+
+      for (const [i, line] of lines.entries()) {
+        const matches = line.matchAll(htmlAltRegex);
+        for (const match of matches) {
+          const matchingContent = match[0];
+          const startIndex = match.indices[0][0];
+          onError({
+            lineNumber: lineNumber + i,
+            range: [startIndex + 1, matchingContent.length],
+          });
+        }
+      }
+    }
+  },
+};
@@ -26,7 +26,7 @@ describe("when A11y rules applied", () => {
      .map((failure) => failure.ruleNames)
      .flat();

-    expect(failuresForExampleFile).toHaveLength(1);
+    expect(failuresForExampleFile).toHaveLength(3);
    expect(failureNames).toContain("no-default-alt-text");
  });
 });
@@ -1,3 +1,5 @@
 # Example Violations

 ![Screen Shot 2022-06-26 at 7 41 30 PM](https://user-images.githubusercontent.com/abcdef.png)
+
+<img alt="image"><img alt="Image">
@@ -11,21 +11,15 @@ describe("GH001: No Default Alt Text", () => {
      ];

      const results = await runTest(strings, altTextRule);
-
-      for (const result of results) {
-        expect(result).not.toBeDefined();
-      }
+      expect(results.length).toBe(0);
    });
    test("html image", async () => {
      const strings = [
        '<img alt="A helpful description" src="https://user-images.githubusercontent.com/abcdef.png">',
      ];

      const results = await runTest(strings, altTextRule);
-
-      for (const result of results) {
-        expect(result).not.toBeDefined();
-      }
+      expect(results.length).toBe(0);
    });
  });
  describe("failures", () => {
@@ -77,6 +71,17 @@ describe("GH001: No Default Alt Text", () => {
      }
    });

+    test("flags multiple consecutive inline images", async () => {
+      const strings = ['<img alt="image"><img alt="Image">'];
+      const results = await runTest(strings, altTextRule);
+      expect(results).toHaveLength(2);
+
+      expect(results[0].errorRange).toEqual([11, 5]);
+      expect(results[0].errorDetail).toEqual("Flagged alt: image");
+      expect(results[1].errorRange).toEqual([28, 5]);
+      expect(results[1].errorDetail).toEqual("Flagged alt: Image");
+    });
+
    test("error message", async () => {
      const strings = [
        "![Screen Shot 2022-06-26 at 7 41 30 PM](https://user-images.githubusercontent.com/abcdef.png)",

@@ -0,0 +1,60 @@
+const noEmptyStringAltRule = require("../src/rules/no-empty-alt-text");
+const runTest = require("./utils/run-test").runTest;
+
+describe("GH003: No Empty Alt Text", () => {
+  describe("successes", () => {
+    test("html image", async () => {
+      const strings = [
+        '<img alt="A helpful description" src="https://user-images.githubusercontent.com/abcdef.png">',
+        "`<img alt='' src='image.png'>`", // code block
+      ];
+
+      const results = await runTest(strings, noEmptyStringAltRule);
+      expect(results).toHaveLength(0);
+    });
+  });
+  describe("failures", () => {
+    test("HTML example", async () => {
+      const strings = [
+        '<img alt="" src="https://user-images.githubusercontent.com/abcdef.png">',
+        "<img alt='' src='https://user-images.githubusercontent.com/abcdef.png'>",
+        '<img src="cat.png" alt="" /> <img src="dog.png" alt="" />',
+      ];
+
+      const results = await runTest(strings, noEmptyStringAltRule);
+
+      const failedRules = results
+        .map((result) => result.ruleNames)
+        .flat()
+        .filter((name) => !name.includes("GH"));
+
+      expect(failedRules).toHaveLength(4);
+      for (const rule of failedRules) {
+        expect(rule).toBe("no-empty-alt-text");
+      }
+    });
+
+    test("error message", async () => {
+      const strings = [
+        '<img alt="" src="https://user-images.githubusercontent.com/abcdef.png">',
+        '<img src="cat.png" alt="" /> <img src="dog.png" alt="" />',
+      ];
+
+      const results = await runTest(strings, noEmptyStringAltRule);
+
+      expect(results[0].ruleDescription).toMatch(
+        "Please provide an alternative text for the image.",
+      );
+      expect(results[0].errorRange).toEqual([6, 6]);
+
+      expect(results[1].ruleDescription).toMatch(
+        "Please provide an alternative text for the image.",
+      );
+      expect(results[1].errorRange).toEqual([20, 6]);
+      expect(results[2].ruleDescription).toMatch(
+        "Please provide an alternative text for the image.",
+      );
+      expect(results[2].errorRange).toEqual([49, 6]);
+    });
+  });
+});
@@ -17,10 +17,7 @@ describe("GH002: No Generic Link Text", () => {
      ];

      const results = await runTest(strings, noGenericLinkTextRule);
-
-      for (const result of results) {
-        expect(result).not.toBeDefined();
-      }
+      expect(results.length).toBe(0);
    });
  });
  describe("failures", () => {

@@ -4,8 +4,11 @@ describe("usage", () => {
  describe("default export", () => {
    test("custom rules on default export", () => {
      const rules = githubMarkdownLint;
-      expect(rules).toHaveLength(2);
+      expect(rules).toHaveLength(3);
+
      expect(rules[0].names).toEqual(["GH001", "no-default-alt-text"]);
+      expect(rules[1].names).toEqual(["GH002", "no-generic-link-text"]);
+      expect(rules[2].names).toEqual(["GH003", "no-empty-alt-text"]);
    });
  });
  describe("init method", () => {
@@ -17,6 +20,7 @@ describe("usage", () => {
        "no-space-in-links": false,
        "single-h1": true,
        "no-emphasis-as-header": true,
+        "no-empty-alt-text": false,
        "heading-increment": true,
        "no-generic-link-text": true,
        "ul-style": {

@@ -11,7 +11,7 @@ async function runTest(strings, rule, ruleConfig) {
    customRules: [rule],
  };

-  return await Promise.all(
+  const results = await Promise.all(
    strings.map((variation) => {
      const thisTestConfig = {
        ...config,
@@ -21,11 +21,13 @@ async function runTest(strings, rule, ruleConfig) {
      return new Promise((resolve, reject) => {
        markdownlint(thisTestConfig, (err, result) => {
          if (err) reject(err);
-          resolve(result[0][0]);
+          resolve(result[0]);
        });
      });
    }),
  );
+
+  return results.flat();
 }

 exports.runTest = runTest;