How are cross-references and links managed within DITA maps?

November 10, 2023
|By Bryan Tipper

Cross-references and links within DITA maps are managed through the use of <xref> and <link> elements. These elements allow authors to create references to other topics or external resources, enabling seamless navigation within the document or to external content.

Creating a Connected Documentation Experience

Cross-references and links in DITA maps are essential for creating a connected and interactive documentation experience.

Cross-References <xref>

The <xref> element is used to create internal references within a DITA map. It allows authors to link to other topics or sections in the same map, enabling readers to easily navigate between related content. The <xref> element can specify the target topic using attributes like href, keyref, or format.

Links <link>

The <link> element is used to create references to external resources, such as web pages, documents, or multimedia files. It can also be used to link to topics outside the current map. The <link> element specifies the target resource using the href attribute.

Example

In a DITA map for a product user manual, an author wants to create cross-references to related topics and include a link to an external support website:


    <map>
      <title>Product User Manual</title>
      
      <topicref href="introduction.dita" />
      <topicref href="features.dita" />
      <topicref href="troubleshooting.dita" />
      
      <!-- Cross-references within the map -->
      <topicref href="introduction.dita#section1" />
      <topicref href="features.dita#section2" />
      
      <!-- Link to an external support website -->
      <link href="https://www.product-support.com" format="html" scope="external" />
    </map>

In this example:

  • The <topicref> elements reference specific topics within the map, and the href attribute specifies the target topic.
  • Cross-references are created within the map by using # to append a reference to a section within the target topic (e.g., “introduction.dita#section1”).
  • The <link> element is used to create a link to an external support website, specifying the URL in the href attribute.