The xref element

The cross-reference element is used for linking or otherwise cross-referencing text within a topic to other topics, elements within a topic, or resources external to the DITA collection.

The cross-reference (xref) element allows you to link text within the body of a DITA topic to different target resources. Although you can manually specify the text for the cross-reference or link itself, in most cases you should let DITA calculate the text based on the type of resource you are linking to. You specify that you want DITA to calculate the cross-reference text by leaving the element empty. For example, if you cross-reference a figure (fig) element, the cross-reference text may be automatically generated as Figure 15. If you provide text within the xref element, that text will be used as the cross-reference text.

Likewise, if you cross-reference a topic, and leave the xref element empty, the target topic title will be used as the cross-reference text. For examples of automatically-generated cross-reference text, see Sample topic - cross-references.

The cross-reference (xref) element has the following attributes:
href
nominates the address of the resource to be referenced, such as a topic, a block within a topic, a PDF file, an external Web resource, or an e-mail address.
type
describes the type of resource being referenced, such as concept for a DITA concept topic, li for a list item in a list within a topic, fn for a footnote within a topic, fig for a figure within a topic, or table for a table within a topic.
format
describes the file format of resource being referenced, such as dita for a DITA topic, pdf for a PDF file, and html for a Web resource.
scope
indicates whether the referenced resource is within the same document as the topic (local), or whether it is external to the document (external).
The syntax of the href attribute is illustrated through the following examples:
  • Reference to a topic (or the first topic in a composite (ditabase) topic): "file.dita"
  • Reference to a specific topic in a composite (ditabase) topic: "file.dita#topicid"
  • Reference to an element inside a DITA topic: "file.dita#topicid/elementid"
  • Reference to an element in a ditamap: "collection.ditamap#map-branch"
  • Reference to an image: "example.png"
  • Reference to an external resource: "http://www.example.org"