Can cross-references be used within the same DITA topic?

In DITA, it is possible to create cross-references within the same topic. This allows linking to specific sections or elements within the topic, enhancing navigation and readability.

Cross-references within the same DITA topic are useful for creating links that help readers easily navigate large or complex topics. They provide a way to jump between different parts of the same topic, making it simpler to find relevant information.

The <xref> element is commonly used for creating cross-references within DITA topics, both for linking to content within the same topic and for referencing content in other topics. The href attribute specifies the target location. When used within the same topic, this attribute references an element or section by its ID.

To create an internal cross-reference within the same topic, the ID of the target element is provided as the value of the href attribute in the <xref> element.


A DITA topic about “Frequently Asked Questions” (faq.dita) requires a cross-reference to a specific question and its answer within the same topic:

<topic id="faq">
  <title>Frequently Asked Questions</title>
  <question id="q1">How do I get started?</question>
  <p>For beginners, getting started is easy.</p>
  <question id="q2">What are the system requirements?</question>
  <p>The system requirements depend on your chosen platform.</p>
  <question id="q3">How can I contact support?</question>
  <p>Contact our support team at [email protected].</p>
  <!-- Cross-references within the same topic -->
  <p>For information on getting started, see <xref href="#q1"/>.</p>
  <p>Details on system requirements can be found in <xref href="#q2"/>.</p>
  <p>If you need support, please refer to <xref href="#q3"/>.</p>

In this example:

  • The “Frequently Asked Questions” topic contains several questions and answers.
  • Cross-references are created using the <xref> element within the same topic, linking to specific questions by referencing their IDs.