Create a cross-reference to another topic

You can insert a cross-reference that creates a link to another topic. You create a cross-reference by inserting an <xref> element.

DITA Best Practices recommend using cross-references sparingly since they break the principle of creating standalone topics. Cross-references in 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 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: The cursor must be within an element that allows <xref> elements.
  3. Search for the topic you want to reference.
  4. Right-click the topic and select Oxygen Editor > Insert as XRef.
    You can select a topic from any of the views, such as the Search Results view, Documents view, or DITA Map view.
    The cross-reference is inserted where the cursor was placed.