Menu
Open source

Write useful link text

Link text is important for search engines and users, and is critical for accessibility. It’s the visible, clickable text in an HTML hyperlink.

The primary purpose of link text is to give users a short summary of the link destination content.

Summary

When writing link text, pay attention to words, quantity of links, and the length of link text.

Words

  • Make link text obviously reflect what the next page is about.

  • Don’t use words such as Click here, More, and Read more as standalone link text, because they can be confusing when a screen reader reads them out of context.

  • When linking to a GitHub repository, include repository in the sentence text or link text.

    For example:

    • To learn more, go to the [faro-web-sdk]() repository.
    • To learn more about Grafana Faro, go to its [repository]().
  • When linking from outside of a documentation page, include documentation in the text.

Quantity

Aim for no more than two links per paragraph.

Some links are essential for additional context, and others are nice to have but not necessary.

Using too many links on a page makes it difficult for a user to read the content.

Length

  • Keep link text short and concise.
  • Never start with articles: a, an, or the.
  • Don’t link whole sentences; aim for a maximum of four to five words.

Examples

UseDon’t use
[Learn more about cluster navigation]() or learn more about [cluster navigation]()[Learn more]()
[our <company name> products]() or [<company name> products]()[our products]()
visit the [<company name> website]() or visit [<company name>.com]()[visit our website]()
[SNMP exporter]()[exporter]()
[KubeCon + CloudNativeCon North America 2022]()[KubeCon event]()
The basic [definition of cardinality]()The [basic definition]() of cardinality
refer to [Configure Kubernetes Monitoring]()[refer to Configure Kubernetes Monitoring]()