Types of cross-references

A cross-reference is used in DITA to link or associate one piece of content with another. The cross-reference (xref) element is the primary mechanism for cross-referencing, but other elements also have cross-referencing functions.

In DITA, cross-referencing is more than simple hyperlinking, or references to page numbers or section titles. Topics, paragraphs, sections, steps, figures, tables and many other DITA elements can be cross-referenced, along with resources external to the DITA content such as Web addresses, network files, and e-mail addresses.

Cross-references are implemented primarily through the xref element and its href attribute. Also key to cross-referencing in DITA is the id attribute: only elements with an id attribute can be cross-referenced.

Cross-referencing features can sometimes be found in unexpected places. For example, the lq element includes an href attribute, used for storing the URL of the source of the quotation, if applicable. The source element in a topic's prolog and the link element in the related-links section also have an href attribute to store the URL of the original source of the topic content, if applicable.

Cross-references to different elements are resolved, when the collection is processed (published), in different ways. For example, a cross-reference to a step element may be rendered as the step number in the output.

The DITA syntax for referencing elements within the same topic is #[topicid]/[elementid].

Avoid generic cross-references to simple paragraphs; instead, cross-references should be to the topic as a whole.