Skip to main content


Use descriptive link text that tell the user where a link will take them without needing to read the surrounding text.

People who use screen reading software can jump from one link to the next in a document without reading the text in between. Many users scan through documents looking for links. Descriptive link text helps these users scan documents quickly.

Use the following guidelines in link text:

  • Don’t use phrases like “click here”, “read more”, “this document”, “this article”, or a URL in the text of a link.
  • Keep link text short where possible.
  • Link text should be unique. Don’t use the same link text to link to different pages.
  • Place important words at the beginning of link text.
  • If a link downloads a file, write text to indicate this action as well as the file type.
Not Recommended
Not Recommended
Not Recommended

Write descriptive links that make sense without the surrounding text.


You may need to rewrite a sentence so that the link makes sense in the sentence.

If you’re adding a link to a heading in Chef’s documentation, use the full heading text:


To make a link in Markdown, put the link text in square brackets followed by the link URL in parentheses:

[Ruby Programming Language](

relref shortcode

We recommend using Hugo’s built-in relref shortcode for making relative links to other pages in Chef’s documentation. If a link is made to a page that does not exist, the site build will fail when Hugo generates a preview of the site. This will help us prevent dead links in our own documentation if a page is moved or deleted.

To format link to pages:

  • [link text]({{< relref "some_page" >}})
  • [link text]({{< relref "section/some_page" >}})

To format links to headings:

  • [link text]({{< relref "#heading_on_this_page" >}})
  • [link text]({{< relref "some_page#heading_on_other_page" >}})
  • [link text]({{< relref "section/some_page#heading_on_other_page" >}})


relref doesn’t validate links to headings, only page links. Double check your headings when adding or updating heading links.
Edit this page on GitHub

Thank you for your feedback!


Search Results