What is the role of the <linktext> element in DITA cross-references?

In DITA, the <linktext> element is used to define custom link text for hyperlinks. It allows authors to specify alternative text to be displayed for a hyperlink, which can be different from the content of the linked resource.

DITA provides a mechanism to create hyperlinks to external resources or sections within topics using the <xref> element or other linking elements. By default, the text within the <xref> element is used as the link text that readers click on. However, there are cases where different text should be displayed for the hyperlink while maintaining a specific reference.

The <linktext> element allows authors to specify the text to be displayed as the link for the reference. It is placed within the content of the <xref> element. This is particularly useful to provide a more descriptive or user-friendly link text while keeping the reference itself clear and consistent.


An external link to a software user guide in a DITA topic can be customized by using the <linktext> element:

<p>To learn more about the software, refer to the <xref href="https://example.com/user-guide.pdf">
  <linktext>User Guide</linktext>

In this example:

  • The <xref> element references an external PDF user guide at “https://example.com/user-guide.pdf.”
  • The <linktext> element specifies that the link should display “User Guide.”

When readers encounter this hyperlink, they will see “User Guide” as the clickable link text. However, the actual link references the external PDF.