Rule - MD059

Property	Value
Aliases	md059, descriptive-link-text
Autofix Available	No
Enabled By Default	Yes

Summary

Link text must be descriptive.

Reasoning

Accessibility

Placeholder link text such as click here, here, link, and more provides no context for screen reader users who navigate by links alone. Descriptive link text ensures that the purpose of the link is clear without surrounding context, improving accessibility.

Examples

Failure Scenarios

This rule triggers when the text associated with a link contains any of the specified placeholders, such as click here, here, link, or more.

To read more, [click here](#some-section).

Explanation: This example fails because the link text click here is in the list of prohibited phrases. The rule checks the interpreted link text (case-insensitive, trimmed) against the prohibited-phrases configuration.

Unlike the previous example, this case uses a full reference link where the label and the link definition share the same text.

Go to this [link][some-link].

[some-link]: /url

Explanation: This example fails because the link text link is in the list of prohibited phrases.

Unlike the previous example, this case uses a collapsed reference link — the same label with no link definition on the same line.

Go here for [more][] information.

[more]: /url

Explanation: This example fails because the link text more is in the list of prohibited phrases.

Unlike the previous collapsed reference link, this case uses a shortcut reference link — the label [more] appears only once and the link definition [more]: /url supplies the URL without re-stating the label on the link line.

Go here for [more] information.

[more]: /url

Explanation: This example fails because the link text more is in the list of prohibited phrases.

Unlike the previous examples, this case shows that leading/trailing spaces and multiple internal spaces are ignored when evaluating the link text.

To read more, [ Click  Here ](#some-section).

Explanation: This example also fails because, after trimming spaces and converting to lowercase, the link text becomes click here, which is a prohibited phrase. The rule normalizes the text before checking against the prohibited list.

Unlike the previous scenarios, which all use the default prohibited-phrases list, this case uses a custom prohibited-phrases value of click one here that replaces the default list.

To read more, [click one here](#some-section).

Explanation: This example fails because the custom prohibited-phrases list includes click one here. The default phrases (click here, here, link, more) are no longer checked unless explicitly re-included in the custom list.

Unlike the previous inline example, this case uses the bare default phrase here as the entire link text.

See [here](#some-section) for details.

Explanation: This example fails because the link text here is one of the four default prohibited phrases.

Correct Scenarios

This rule does not trigger when the interpreted link text is not one of the prohibited phrases, such as using a descriptive phrase.

Go to [this section](#some-section).

Explanation: This example passes because the link text this section is not in the list of prohibited phrases (click here, here, link, more). The rule only flags link text that matches the prohibited list exactly (after normalization).

Unlike the previous example, this case shows that a longer link text (Click here to learn more) that merely contains prohibited words as substrings still does not trigger the rule, because the rule matches the normalized link text exactly against the prohibited list rather than by substring.

[Click here to learn more](#some-section).

Explanation: This example passes because the link text Click here to learn more does not exactly match any prohibited phrase (click here, here, link, more). The rule requires an exact match after normalization, not a substring match.

Unlike the previous examples, which use the default prohibited-phrases list, this case uses a custom list of click one here, so the default phrase click here is no longer prohibited.

To read more, [click here](#some-section).

Explanation: This example passes because the custom prohibited-phrases list (click one here) replaces the default list. click here is no longer checked, so the rule does not trigger.

Fix Description

Automatic fixing is not possible because determining appropriate, descriptive link text requires understanding the context and intent of the link, which is ambiguous without human judgment. Replacing generic text with specific content could result in incorrect or misleading descriptions.

Configuration

Prefixes
plugins.md059.
plugins.descriptive-link-text.

Value Name	Type	Default	Description
enabled	boolean	True	Whether the Rule Plugin is enabled.
prohibited-phrases	string	"click here,here,link,more"	Comma-separated list of phrases that are prohibited.

Origination of Rule

This rule is largely inspired by the MarkdownLint rule MD059.