Create a cross-reference to an element within a topic

You can insert a cross-reference that creates links to an element within a topic.

For example, you can have a bulleted list that links each item to a corresponding section in the topic. Or each bulleted list item can link to a section in another topic.

You create these links by adding an @id attribute to the target element and then inserting an <xref> element that references the value of that @id attribute.

To create an internal cross-reference:

  1. Search for and open the topic you want to link to.
  2. In the topic, add an ID @id attribute for the element that you want to link to.

    For example, if you want to link to a section in the topic, you would add an ID to the <section> element: <section id="IntroSection">

    1. Right-click the element and select Edit Attributes.
    2. From the Name drop-down list, select id.
    3. In the Value field, enter a unique value.
    4. Click OK.
  3. Open the topic you want to add the cross-reference in.
  4. Place the cursor where you want to insert the cross-reference.
    Note: The cursor must be within an element that allows <xref> elements.
  5. Right-click the topic that you want to link to, and select Oxygen Editor > Insert as XRef .
    You can select the topic from any of the views, such as the Search Results view, Documents view, or DITA Map view.
  6. Right-click the cross-reference and and select Edit Attributes.
  7. From the Name drop-down list, select href.
  8. In the Value field, add the topic ID and the value for the @id attribute that you entered for the element you want to reference.
    Use the following syntax: 
    filename.xml#topicid/idstring
    • filename is the file name of the topic (this should already appear in the Value field)
    • topicid is the root ID of the topic
    • idstring is the ID of the target element
    For example, if your topic ID is acb4321987654321 and the target element's ID is firstbullet, then the value would be: 
    acb4321987654321.xml#acb4321987654321/firstbullet
  9. From the Name drop-down list, select keyref.
  10. In the Value field, add a forward slash and the value for the @id attribute that you entered for the element you want to reference.
    Use the following syntax: 
    topicid/idstring
    • topicid is the root ID of the topic
    • idstring is the ID of the target element
    For example, if your topic ID is acb4321987654321 and the target element's ID is firstbullet, then the value would be: 
    acb4321987654321/firstbullet
  11. Optional: In the <xref> element, type any text that you want to display for the link.
    You can add text like "link", "here", "click here", and so on.