diff --git a/markdownlint/docs/TOP001.md b/markdownlint/docs/TOP001.md index ac464ee333b..1de4c411c18 100644 --- a/markdownlint/docs/TOP001.md +++ b/markdownlint/docs/TOP001.md @@ -4,7 +4,12 @@ Tags: `accessibility`, `links` Aliases: `descriptive-link-text` -This rule is triggered when a link has a text label that uses the words "this" or "here", for example: +This rule is triggered when a link has a text label that meets one of the following criteria: + +- Uses the words "this" or "here" +- Exactly matches one of our blacklisted link texts (commonly used text labels that are insufficiently descriptive) + +Example of links that have text labels that include "this" or "here": ```markdown You can read more about variables in JavaScript [here](https://example.com). @@ -18,7 +23,7 @@ You can read more about [variables in JavaScript](https://example.com). [An in-depth article about closures in JavaScript](https://example.com) provides more information. ``` -Note that this rule only flags text labels containing the words "this" or "here", even if the text is somewhat descriptive: +Note that even if the text is somewhat descriptive, this rule will still flag occurrences of "this" or "here": ```markdown [Here is a comprehensive guide to understanding closures](https://example.com). @@ -36,6 +41,20 @@ Additionally, consider including relevant keywords in the link text to provide m For more information, refer to the [official documentation on closures in JavaScript](https://example.com). ``` +This rule is also triggered if the entire link text exactly matches any of our blacklisted texts, which consists of commonly used text labels that are not sufficiently descriptive while not containing "this" or "here". Examples include (but are not limited to) "video", "article", "an article", "docs", "the docs", "documentation", and "homepage": + +```markdown +For more information, watch this [video](https://example.com) about the CSS box model. +You can read more about it in the [documentation](https://example.com). +``` + +The above links can be rephrased to be sufficiently descriptive by themselves: + +```markdown +For more information, watch this [video about the CSS box model](https://example.com). +You can read more about it in the [Proc class documentation](https://example.com). +``` + ## Rationale - Descriptive link text improves accessibility by providing clear and meaningful context about the link's destination. Links with text labels using the words "this" or "here" tend to be less descriptive and may not effectively convey the purpose of the link to users, especially those using assistive technologies. By using specific and relevant keywords in the link text, you can enhance the user experience and make it easier for users to understand the context and purpose of the link. +Descriptive link text improves accessibility by providing clear and meaningful context about the link's destination. Links with text labels using the words "this" or "here" tend to be less descriptive and may not effectively convey the purpose of the link to users, especially those using assistive technologies. Similarly, text labels like "video", "article" or "docs" act in the same way for users of assistive technologies, requiring knowledge of the surrounding non-link text for context. By using specific and relevant keywords in the link text, you can enhance the user experience and make it easier for users to understand the context and purpose of the link.