<xref>: How do you use the <xref> element to create cross-references within a DITA topic to other sections or topics within the same document or map?

November 10, 2023
|By Bryan Tipper

The <xref> element in DITA XML is used to create cross-references within a DITA topic to other sections or topics within the same document or map. Cross-references are essential for helping readers navigate complex documentation and quickly access related information. They enable seamless linking between different parts of the content, providing context and improving the overall user experience.

Usage of <xref> Element

To use the <xref> element, you include it within the content of a DITA topic, specifying the target using the “href” attribute. The target can be the ID of another topic or section within the same document or map. When a reader clicks on the cross-reference, they are taken directly to the linked location. This is particularly useful for creating links to headings, figures, tables, or any specific section you want to reference within your documentation.

Example:

Here’s an example of how to use the <xref> element to create a cross-reference to another section within a DITA topic:


<topic id="example_topic">
  <title>Advanced Configuration</title>
  <body>
    <h1 id="config_heading">Configuration Settings</h1>
    <p>This section provides details on configuring the software. For more information, refer to the <xref href="#config_heading">Configuration Settings</xref> section.</p>
  </body>
</topic>

In this example, the <xref> element is used to create a cross-reference to the “Configuration Settings” section within the same DITA topic, allowing readers to jump directly to that section for more details.