Skip to content

Commit

Permalink
Amend TOP001 docs with new blacklisted label criteria
Browse files Browse the repository at this point in the history
  • Loading branch information
MaoShizhong committed Aug 2, 2024
1 parent e383114 commit e52538e
Showing 1 changed file with 22 additions and 3 deletions.
25 changes: 22 additions & 3 deletions markdownlint/docs/TOP001.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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).
Expand All @@ -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.

0 comments on commit e52538e

Please sign in to comment.