Create a cross-reference to another topic

You can insert a link to directly reference another element.

The <xref> element lets you make a cross-reference from one topic to another.

DITA Best Practices recommend using cross-references sparingly since they break the principle of creating "standalone topics". Cross-references, which are directly inserted into a topic, can cause issues when attempting to reuse the topic in another map. Consider using a relationship table to manage the links between the topics or organizing your table of contents to imply the relationship between the topics.

To create a cross-reference:

  1. Open and lock the topic in your XML editor.
  2. Place the cursor where you want to insert the cross-reference.
    Note: You must be within an element that allows an <xref> element.
  3. Locate the topic you want to reference.
    You can select a topic displayed in any of the views. For example, you can select the topic from the Search Results view, DITA Map view, or from your favorites.
  4. Right-click the reference topic and do one of the following depending on your XML editor:
    • For oXygen XML Editor: Click Oxygen Editor > Insert as Xref.
    • For XMetaL XML Editor: XMetaL Editor > Insert as Xref.
    The cross-reference is inserted where the cursor was placed.