[WIP] Add new rule: no-generic-link-name

README.md

@@ -146,6 +146,7 @@ playground for learning and exploring.
 - **[MD055](doc/md055.md)** *table-pipe-style* - Table pipe style
 - **[MD056](doc/md056.md)** *table-column-count* - Table column count
 - **[MD058](doc/md058.md)** *blanks-around-tables* - Tables should be surrounded by blank lines
+- **[MD059](doc/md059.md)** *descriptive-link-text* - Link text should be descriptive
 
 <!-- markdownlint-restore -->
 
@@ -165,7 +166,7 @@ To implement your own rules, refer to [CustomRules.md](doc/CustomRules.md).
 Tags group related rules and can be used to enable/disable multiple
 rules at once.
 
-- **`accessibility`** - `MD045`
+- **`accessibility`** - `MD045`, `MD059`
 - **`atx`** - `MD018`, `MD019`
 - **`atx_closed`** - `MD020`, `MD021`
 - **`blank_lines`** - `MD012`, `MD022`, `MD031`, `MD032`, `MD047`
@@ -183,7 +184,7 @@ rules at once.
 - **`language`** - `MD040`
 - **`line_length`** - `MD013`
 - **`links`** - `MD011`, `MD034`, `MD039`, `MD042`, `MD051`, `MD052`, `MD053`,
-  `MD054`
+  `MD054`, `MD059`
 - **`ol`** - `MD029`, `MD030`, `MD032`
 - **`spaces`** - `MD018`, `MD019`, `MD020`, `MD021`, `MD023`
 - **`spelling`** - `MD044`

doc-build/md059.md

@@ -0,0 +1,15 @@
+This rule is triggered when a link is set with non-descriptive text like
+"Click here", "here", or "learn more", giving it a generic accessible name.
+
+Rationale: Screen reader users may navigate through a list of links
+to quickly find content on a page. When the link name is something ambiguous
+like "Learn more", there isn't sufficient context to help the user determine
+whether to follow the link.
+
+Link names should be descriptive and describe the purpose of the link.
+
+To override the default list and configure your own list of banned accessible
+names, set `banned_link_texts_override` in the config.
+
+Note: At this time, this rule only checks against inline Markdown links given
+the complexities of determining the accessible name of an HTML anchor tag.

doc/Rules.md

@@ -2526,6 +2526,34 @@ Some text
 Rationale: In addition to aesthetic reasons, some parsers will incorrectly parse
 tables that don't have blank lines before and after them.
 
+<a name="md059"></a>
+
+## `MD059` - Link text should be descriptive
+
+Tags: `accessibility`, `links`
+
+Aliases: `descriptive-link-text`
+
+Parameters:
+
+- `banned_link_texts`: List of banned link texts (`string[]`, default `[]`)
+
+This rule is triggered when a link is set with non-descriptive text like
+"Click here", "here", or "learn more", giving it a generic accessible name.
+
+Rationale: Screen reader users may navigate through a list of links
+to quickly find content on a page. When the link name is something ambiguous
+like "Learn more", there isn't sufficient context to help the user determine
+whether to follow the link.
+
+Link names should be descriptive and describe the purpose of the link.
+
+To override the default list and configure your own list of banned accessible
+names, set `banned_link_texts_override` in the config.
+
+Note: At this time, this rule only checks against inline Markdown links given
+the complexities of determining the accessible name of an HTML anchor tag.
+
 <!-- markdownlint-configure-file {
   "no-inline-html": {
     "allowed_elements": [

doc/md059.md

@@ -0,0 +1,25 @@
+# `MD059` - Link text should be descriptive
+
+Tags: `accessibility`, `links`
+
+Aliases: `descriptive-link-text`
+
+Parameters:
+
+- `banned_link_texts`: List of banned link texts (`string[]`, default `[]`)
+
+This rule is triggered when a link is set with non-descriptive text like
+"Click here", "here", or "learn more", giving it a generic accessible name.
+
+Rationale: Screen reader users may navigate through a list of links
+to quickly find content on a page. When the link name is something ambiguous
+like "Learn more", there isn't sufficient context to help the user determine
+whether to follow the link.
+
+Link names should be descriptive and describe the purpose of the link.
+
+To override the default list and configure your own list of banned accessible
+names, set `banned_link_texts_override` in the config.
+
+Note: At this time, this rule only checks against inline Markdown links given
+the complexities of determining the accessible name of an HTML anchor tag.

lib/md039.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
 import { addErrorContext } from "../helpers/helpers.cjs";
-import { getReferenceLinkImageData, filterByTypesCached } from "./cache.mjs";
+import { filterByTypesCached } from "./cache.mjs";
 
 /**
  * Adds an error for a label space issue.
@@ -35,40 +35,25 @@ function addLabelSpaceError(onError, label, labelText, isStart) {
   );
 }
 
-/**
- * Determines if a link is a valid link (and not a fake shortcut link due to parser tricks).
- *
- * @param {import("markdownlint").MicromarkToken} label Label token.
- * @param {import("markdownlint").MicromarkToken} labelText LabelText token.
- * @param {Map<string, any>} definitions Map of link definitions.
- * @returns {boolean} True iff the link is valid.
- */
-function validLink(label, labelText, definitions) {
-  return (label.parent?.children.length !== 1) || definitions.has(labelText.text.trim());
-}
-
 /** @type {import("markdownlint").Rule} */
 export default {
   "names": [ "MD039", "no-space-in-links" ],
   "description": "Spaces inside link text",
   "tags": [ "whitespace", "links" ],
   "parser": "micromark",
   "function": function MD039(params, onError) {
-    const { definitions } = getReferenceLinkImageData();
     const labels = filterByTypesCached([ "label" ])
       .filter((label) => label.parent?.type === "link");
     for (const label of labels) {
       const labelTexts = label.children.filter((child) => child.type === "labelText");
       for (const labelText of labelTexts) {
         if (
-          (labelText.text.trimStart().length !== labelText.text.length) &&
-          validLink(label, labelText, definitions)
+          (labelText.text.trimStart().length !== labelText.text.length)
         ) {
           addLabelSpaceError(onError, label, labelText, true);
         }
         if (
-          (labelText.text.trimEnd().length !== labelText.text.length) &&
-          validLink(label, labelText, definitions)
+          (labelText.text.trimEnd().length !== labelText.text.length)
         ) {
           addLabelSpaceError(onError, label, labelText, false);
         }

lib/md059.mjs

@@ -0,0 +1,52 @@
+// @ts-check
+
+import { addErrorContext } from "../helpers/helpers.cjs";
+import { filterByTypesCached } from "./cache.mjs";
+
+const defaultBannedNames = [
+  "click here",
+  "here",
+  "learn more",
+  "link",
+  "more",
+  "read more"
+];
+
+/**
+ * Downcases a string and strips extra white spaces and punctuations.
+ *
+ * @param {string} text String to transform.
+ * @returns {string} Stripped and downcased string.
+ */
+function normalizeText(text) {
+  return text
+    .toLowerCase()
+    .replace(/\W+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** @type {import("markdownlint").Rule} */
+export default {
+  "names": [ "MD059", "descriptive-link-text" ],
+  "description": "Link text should be descriptive",
+  "tags": [ "links", "accessibility" ],
+  "parser": "micromark",
+  "function": function MD059(params, onError) {
+    // Allow consumer to define their own banned names list.
+    const bannedNames = new Set(params.config.banned_link_texts_override || defaultBannedNames);
+
+    const labels = filterByTypesCached([ "label" ])
+      .filter((label) => label.parent?.type === "link");
+
+    for (const label of labels) {
+      const labelTexts = label.children.filter((child) => child.type === "labelText");
+      for (const labelText of labelTexts) {
+        const { text } = label;
+        if (bannedNames.has(normalizeText(text))) {
+          addErrorContext(onError, labelText.startLine, text);
+        }
+      }
+    }
+  }
+};

lib/rules.mjs

@@ -53,6 +53,7 @@ import md054 from "./md054.mjs";
 import md055 from "./md055.mjs";
 import md056 from "./md056.mjs";
 import md058 from "./md058.mjs";
+import md059 from "./md059.mjs";
 
 const rules = [
   md001,
@@ -108,7 +109,8 @@ const rules = [
   md055,
   md056,
   // md057: See https://github.com/markdownlint/markdownlint
-  md058
+  md058,
+  md059
 ];
 for (const rule of rules) {
   const name = rule.names[0].toLowerCase();

schema/markdownlint-config-schema-strict.json

@@ -1716,6 +1716,42 @@
       "type": "boolean",
       "default": true
     },
+    "MD059": {
+      "description": "MD059/descriptive-link-text : Link text should be descriptive : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md059.md",
+      "type": [
+        "boolean",
+        "object"
+      ],
+      "properties": {
+        "banned_link_texts": {
+          "description": "List of banned link texts",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "default": true
+    },
+    "descriptive-link-text": {
+      "description": "MD059/descriptive-link-text : Link text should be descriptive : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md059.md",
+      "type": [
+        "boolean",
+        "object"
+      ],
+      "properties": {
+        "banned_link_texts": {
+          "description": "List of banned link texts",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "default": true
+    },
     "headings": {
       "description": "headings : MD001, MD003, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD026, MD036, MD041, MD043",
       "type": "boolean",

schema/markdownlint-config-schema.json

@@ -1716,6 +1716,36 @@
       "type": "boolean",
       "default": true
     },
+    "MD059": {
+      "description": "MD059/descriptive-link-text : Link text should be descriptive : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md059.md",
+      "type": "boolean",
+      "properties": {
+        "banned_link_texts": {
+          "description": "List of banned link texts",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "default": true
+    },
+    "descriptive-link-text": {
+      "description": "MD059/descriptive-link-text : Link text should be descriptive : https://github.com/DavidAnson/markdownlint/blob/v0.37.3/doc/md059.md",
+      "type": "boolean",
+      "properties": {
+        "banned_link_texts": {
+          "description": "List of banned link texts",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        }
+      },
+      "default": true
+    },
     "headings": {
       "description": "headings : MD001, MD003, MD018, MD019, MD020, MD021, MD022, MD023, MD024, MD025, MD026, MD036, MD041, MD043",
       "type": "boolean",

test/bare-urls.md

@@ -12,7 +12,7 @@ Visit https://example.com, then refresh. {MD034}
 
 The site (https://example.com) is down. {MD034}
 
-<!-- markdownlint-disable line-length no-inline-html -->
+<!-- markdownlint-disable line-length no-inline-html descriptive-link-text -->
 
 Some documents use <a href="https://example.com">to link</a>.
 

test/descriptive-link-text-override-config.md

@@ -0,0 +1,17 @@
+# Descriptive link text override config
+
+[Go here](https://example.com/javascript/about) {MD059}
+
+[Learn more](https://example.com/javascript/about).
+
+[Click here](https://example.com/javascript/about).
+
+To learn more, go [here!](https://example.com/javascript/about).
+
+To learn more, go to this [link!](https://example.com/javascript/about).
+
+<!-- markdownlint-configure-file {
+  "descriptive-link-text": {
+    "banned_link_texts_override": ["go here"]
+  }
+} -->

test/descriptive-link-text.md

@@ -0,0 +1,23 @@
+# Descriptive link text
+
+[Learn about Javascript](https://example.com/javascript/about)
+
+[Read about Javascript](https://example.com/javascript/about)
+
+Learn about [JavaScript](https://example.com/javascript/about).
+
+[Learn more](https://example.com/javascript/about). {MD059}
+
+[Click here](https://example.com/javascript/about). {MD059}
+
+To learn more, go [here!](https://example.com/javascript/about). {MD059}
+
+To learn more, [click here!!!!](https://example.com/javascript/about). {MD059}
+
+[click-here!!!!](https://example.com/javascript/about). {MD059}
+
+Go to this [link]((https://example.com/javascript/about)). {MD059}
+
+[link][1] {MD059}
+
+[1]: https://example.com/javascript/about

test/fixing-with-front-matter.md

@@ -5,7 +5,7 @@ ignore: this
 # Fixing with Front Matter {MD022}
 Text text text {MD009}   
 
-Text [ link ](url) text {MD039}
+Text [ link ](url) text {MD039} {MD059}
 ## Nested Heading {MD022}
 
 Text {MD047}

test/link-style-no-url-inline-not-possible.md

@@ -60,6 +60,7 @@ Text [email] text
 [email]: user@example.com
 
 <!-- markdownlint-configure-file {
+  "descriptive-link-text": false,
   "link-image-style": {
     "autolink": false,
     "url_inline": false

test/link-style-no-url-inline-possible.md

@@ -61,6 +61,7 @@ Text [email] text
 [email]: user@example.com
 
 <!-- markdownlint-configure-file {
+  "descriptive-link-text": false,
   "link-image-style": {
     "url_inline": false
   }

test/links-alternate.md

@@ -45,5 +45,6 @@ Text [ link ][reference] text. {MD039}
 
 <!-- markdownlint-configure-file {
   "line-length": false,
-  "code-block-style": false
+  "code-block-style": false,
+  "descriptive-link-text": false
 } -->

test/long-lines-long-reference-definitions-stern.md

@@ -17,6 +17,7 @@
 [long-reference-definition]: https://example.com/long/long/long/long/long/long/long/long/long/long/long/long/long
 
 <!-- markdownlint-configure-file {
+  "descriptive-link-text": false,
   "line-length": {
     "stern": true
   }