Andreas/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2025-12-16 14:00:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Add rule MD059/descriptive-link-text "Link text should be descriptive" (fixes #681).

Browse source
This commit is contained in:
Kate Higa 2025-01-06 11:35:17 -05:00 • committed by David Anson
parent 4117394250
commit b8374ec5d2
40 changed files with 1159 additions and 234 deletions
Download patch file Download diff file Expand all files Collapse all files

29
doc/Rules.md
View file

@ -2538,6 +2538,35 @@ 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:
- `link_texts`: List of restricted link texts (`string[]`, default `[]`)
This rule is triggered when a link is set with generic 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, like:
`[Download the budget document]`, `[About markdownlint]`,`[View registration]`,
etc.
To override the default list and configure your own list of banned accessible
names, set `link_texts` in the config.
Note: This rule checks Markdown-style links and ignores HTML-style links.
<!-- markdownlint-configure-file {
"no-inline-html": {
"allowed_elements": [

26
doc/md059.md Normal file
View file

@ -0,0 +1,26 @@
# `MD059` - Link text should be descriptive
Tags: `accessibility`, `links`
Aliases: `descriptive-link-text`
Parameters:
- `link_texts`: List of restricted link texts (`string[]`, default `[]`)
This rule is triggered when a link is set with generic 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, like:
`[Download the budget document]`, `[About markdownlint]`,`[View registration]`,
etc.
To override the default list and configure your own list of banned accessible
names, set `link_texts` in the config.
Note: This rule checks Markdown-style links and ignores HTML-style links.