remark-lint-link-text

A remark-lint plugin that warns against non-descriptive link text.

✅ Check out [W3C’s Web Accessibility Initiative](https://www.w3.org/WAI) to learn more.
🚫 Learn more [here](https://www.w3.org/WAI).

Installation and usage

npm install --save-dev remark-cli @double-great/remark-lint-link-text

Add the plugin to your remark configuration:

"remarkConfig": {
  "plugins": [
    "@double-great/remark-lint-link-text"
  ]
},

List of warnings

• Link text is not descriptive (not-descriptive)
• Link text is not unique (unique)
• Link text is a URL (not-url)
• Link text is missing (empty)
• Linked image is missing alt text (empty-alt-text)
• Link to email does not contain email address in link text (email)

Link text is not descriptive

Pulling from this library’s list of bad link text, any link text that matches this list will be flagged. Using non-specific link text is a failure of WCAG 2.4.9 (AAA).

🚫 The following markdown will cause a warning:

- [click here](https://example.com/team)

✅ The following markdown will not cause a warning:

- [Example team](https://example.com/team)

Configuration:

// disable the rule:
["@double-great/remark-lint-link-text", [1, {"not-descriptive":false}]]
// adjust rule defaults:
["@double-great/remark-lint-link-text", [1, {"not-descriptive":["about","button","can be found here","click","click here","continue","continue reading","details","email","figure","found here","here","learn more","link","more","more details","more here","online","read more","resource","the article","the document","the entry","the link","the page","the post","the site","the website","this article","this document","this entry","this link","this page","this post","this site","this website","url","website"]}]]

💡 For all banned phrases that begin with this or the, any words that come between will also fail. For example “this post”, “this W3C post”, and “this W3C blog post” will all fail.

Link text is not unique

This warning relates to WCAG 2.4.9 Link Purpose (Link Only) (AAA) and WCAG 3.2.4 Consistent Navigation (AA). Links with different purposes and destinations should have different link text. Descriptive link text communicates a link’s purpose even when the context is missing. A screen reader listing all of the links on a page is an example where the context would be missing.

🚫 The following markdown will cause a warning:

- [Example](https://example.com/team)
- [Example](https://example.com/about)

✅ The following markdown will not cause a warning:

- [Example team](https://example.com/team)
- [About Example](https://example.com/about)

Configuration:

// disable the rule:
["@double-great/remark-lint-link-text", [1, {"unique":false}]]

💡 This check does not account for techniques that use aria-label or aria-labelledby attributes to provide additional link context. Context provided by content that surrounds the link, as allowed by WCAG 2.4.4 Link Purpose (In Context) (A), is not considered by this check.

Link text is a URL

WCAG 2.4.4 Link Purpose (In Context) (A) considers a link containing text that gives a description of the information at that URL a sufficient technique. When a URL is the link text, screen readers have to listen while the reader pronounces every single character of a URL. Audibly, this is less descriptive and more time consuming to listen to than descriptive link text. WebAIM’s Links and Hypertext page explains the challenges of URLs as links.

🚫 The following markdown will cause a warning:

[https://www.w3c.org/WAI/fundamentals/accessibility-intro/](https://www.w3c.org/WAI/fundamentals/accessibility-intro/)

When read aloud, users will hear “h t t p s colon slash slash w w w dot w 3 c dot org slash w a i slash fundementals slash accessibility dash intro slash, link”.

✅ The following markdown will not cause a warning:

[Introduction to Web Accessibility](https://www.w3c.org/WAI/fundamentals/accessibility-intro/)

When read aloud, users will hear “Introduction to Web Accessibility, link”.

Configuration:

// disable the rule:
["@double-great/remark-lint-link-text", [1, {"not-url":false}]]

💡 This check is at odds with some stylistic guidelines, like APA. The APA Style’s Accessible URLs page provides some rationale for their guidelines as it relates to WCAG 2.4.4.

Link text is missing

In markdown, missing link text is often an oversight. Although an <a> element without a href attribute is valid HTML, WebAIM suggests that empty links can be very confusing to keyboard and screen reader users and should be avoided completely.

🚫 The following markdown will cause a warning:

[](https://example.com)

✅ The following markdown will not cause a warning:

[Example](https://example.com)

Configuration:

// disable the rule:
["@double-great/remark-lint-link-text", [1, {"empty":false}]]

Linked image is missing alt text

When an image is the only content in a link, alt text is required. In this context, missing alt text is a failure of WCAG 2.4.4 (A), 2.4.9 (AAA), and 4.1.2 (A).

🚫 The following markdown will cause a warning:

[![](https://example.com/logo.svg)](https://example.com)

✅ The following markdown will not cause a warning:

[![Example logo](https://example.com/logo.svg)](https://example.com)

Configuration:

// disable the rule:
["@double-great/remark-lint-link-text", [1, {"empty-alt-text":false}]]

💡 When an image is the only content in a link, the image’s alt text effectively becomes the link text. Based on WCAG 2.4.4 Link Purpose (In Context) (A), the alt text should describle the function of the link (instead of describing the image).

Link to email does not contain email address in link text

When linking to an email address, using mailto:, the email address should be in the link text. This provides users with context for what will happen when interacting with the link (a new email message will open in email application). Also, email in the link text is useful context when the link can’t be activated (plain text paste, printed page).

🚫 The following markdown will cause a warning:

[Email me](mailto:[email protected])

✅ The following markdown will not cause a warning:

[[email protected]](mailto:[email protected])

[[email protected]](mailto:[email protected]?subject=hello)

Configuration:

// disable the rule:
["@double-great/remark-lint-link-text", [1, {"email":false}]]

More link text resources

• A11y Collective: The Perfect Link
• Get Stark: The endless search for “here” in the unhelpful “click here” button
• NC State University: Accessible Hyperlinks
• Penn State: Link Text
• WCAG 2.4.4: Link Purpose
• WCAG 2.4.9: Link Purpose (Link Only)
• WCAG 3.2.4: Consistent Identification
• WCAG 4.1.2: Name, Role, Value
• WebAIM: Links and Hypertext - Link Text and Appearance