Use the xref element to provide an inline cross reference. It is commonly used to link to a different location within the current topic, a different topic, a specific location in another topic, or an external resource. The target of the cross-reference is specified using the href or keyref attributes.
When creating a cross-reference, link to the element structure, not the title element of the object. For example, to create a cross-reference to a figure, link to the fig element, not the title element within the fig element. Output processing determines whether the text of the title element is used to render the cross-reference.
Cross references that link to elements in other topics can employ key-based addressing by using the keyref attribute. This enables the cross-reference to point to different topics in the context of different top-level maps. Cross references that employ direct URI-based addressing using the href attribute create dependencies; if the topic with the cross-reference is included in a map, the target topic also might need to be included for the cross-reference to be resolvable in the context of that map. While you can use conditional processing to have different cross-references for different contexts, it is usually easier and more effective to use keys. By using keys, the cross-reference can be independent of the contexts it might be used in, because it is up to each different map to bind the key used by the cross-reference to the appropriate target.
In many cases it is best to avoid inline cross references in favor of links of links that are generated by the related-links element or relationship tables. Such links typically are rendered at the end of the topic. This prevents readers from leaving a topic and missing important information. Using relationship tables also enables the links to be managed at a DITA map level, making it possible for topics to be quickly integrated into new contexts without breaking links.
See appendix for information about this element in OASIS document type shells.
- This example shows a cross-reference to another topic; that topic's title
will typically be used as the link
<p>Background information about DITA is provided in the topic entitled <xref href="whatsdita.dita"></xref>.</p>
- The same cross reference could be created using keyref
instead of href; using keyref allows the
link to be redirected to different resources when used in different map
<p>Background information about DITA is provided in the topic entitled <xref keyref="whatisdita"></xref>.</p>
- This example shows cross-references to another topic; the supplied text will
be used as the link
<p><xref href="whatsdita.dita#tmmdita">Background information about DITA</xref> is provided free of charge. For a context free cross reference, the keyref attribute can also link to a topic for <xref keyref="whatisdita">information about DITA</xref>.</p>
- If you are linking to an element inside of a topic, use the following format
in the href attribute:
- The keyref attribute can
also be used to link to an element inside of a topic; in this case the key
represents the topic, but the element ID remains the same:
- If you are linking within the same file, you can leave off the file name
portion filename.dita. So, for a section with the ID "mysection", use:
- Alternatively, if the link is to an element
within the same topic you can use:
- For a list item within that section, assuming the item has an ID of
- Alternatively, because the link is to an
element within the same topic, you can use:
<xref href="http://www.example.com/docview.wss?rs=757&context=SSVNX5" scope="external">Part number SSVNX5</xref>