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.

Content models

See appendix for information about this element in OASIS document type shells.


- topic/xref


See DITA addressing for details on using URI references and Indirect key-based addressing for details on using key references.

If your URL has an ampersand (&) in it, you need to code that using a entity reference. For example, this URL includes an & character:
When used in an @href attribute, the ampersand must be entered as &amp; as shown here:
<xref href="http://www.example.com/docview.wss?rs=757&amp;context=SSVNX5"
scope="external">Part number SSVNX5</xref>


The following attributes are available on this element: Universal attribute group, Link relationship attribute group, outputclass, and @keyref.

Return to main page.