Andreas/markdownlint
1
0
Fork 0
mirror of https://github.com/DavidAnson/markdownlint.git synced 2025-09-21 21:30:47 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Update new rule MD059/descriptive-link-text for project-level consistency.

Browse source
This commit is contained in:
David Anson 2025-02-13 22:07:27 -08:00
parent b8374ec5d2
commit 571c2353ea
23 changed files with 466 additions and 383 deletions
Download patch file Download diff file Expand all files Collapse all files

30
doc/Rules.md
View file

@ -2548,24 +2548,28 @@ Aliases: `descriptive-link-text`
Parameters:
- `link_texts`: List of restricted link texts (`string[]`, default `[]`)
- `prohibited_texts`: Prohibited link texts (`string[]`, default `["click
here","here","link","more"]`)
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.
This rule is triggered when a link has generic text like `[click here](...)` or
`[link](...)`.
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 text should be descriptive and communicate the purpose of the link (e.g.,
`[Download the budget document](...)` or `[CommonMark Specification](...)`).
This is especially important for screen readers which sometimes present links
without context.
Link names should be descriptive and describe the purpose of the link, like:
`[Download the budget document]`, `[About markdownlint]`,`[View registration]`,
etc.
By default, this rule prohibits a small number of common English words/phrases.
To customize that list of words/phrases, set the `prohibited_texts` parameter to
an `Array` of `string`s.
To override the default list and configure your own list of banned accessible
names, set `link_texts` in the config.
Note: For languages other than English, use the `prohibited_texts` parameter to
customize the list for that language. It is *not* a goal for this rule to have
translations for every language.
Note: This rule checks Markdown-style links and ignores HTML-style links.
Note: This rule checks Markdown links; HTML links are ignored.
More information: <https://webaim.org/techniques/hypertext/>
<!-- markdownlint-configure-file {
"no-inline-html": {

30
doc/md059.md
View file

@ -6,21 +6,25 @@ Aliases: `descriptive-link-text`
Parameters:
- `link_texts`: List of restricted link texts (`string[]`, default `[]`)
- `prohibited_texts`: Prohibited link texts (`string[]`, default `["click
here","here","link","more"]`)
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.
This rule is triggered when a link has generic text like `[click here](...)` or
`[link](...)`.
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 text should be descriptive and communicate the purpose of the link (e.g.,
`[Download the budget document](...)` or `[CommonMark Specification](...)`).
This is especially important for screen readers which sometimes present links
without context.
Link names should be descriptive and describe the purpose of the link, like:
`[Download the budget document]`, `[About markdownlint]`,`[View registration]`,
etc.
By default, this rule prohibits a small number of common English words/phrases.
To customize that list of words/phrases, set the `prohibited_texts` parameter to
an `Array` of `string`s.
To override the default list and configure your own list of banned accessible
names, set `link_texts` in the config.
Note: For languages other than English, use the `prohibited_texts` parameter to
customize the list for that language. It is *not* a goal for this rule to have
translations for every language.
Note: This rule checks Markdown-style links and ignores HTML-style links.
Note: This rule checks Markdown links; HTML links are ignored.
More information: <https://webaim.org/techniques/hypertext/>