`<xref>`

A cross reference is an inline link. A cross reference can link to a different location within the current topic, another topic, a specific location in another topic, or an external resource such as a PDF or web page.

Content model

(Text | <keyword> | <ph> |  |  |  |  | <line-through> | <overline> |  |  | <tt> |  | <q> | <term> | <text> | <tm> | <cite> | <data> | <sort-as> | <draft-comment> | <foreign> | <required-cleanup> | <image> | <desc> )*

Zero or more

Attributes

The following attributes are available on this element: link-relationship attributes, universal attributes, and @keyref.

The following attributes are available on this element: universal attributes and the attributes defined below.

@format (link-relationship attributes): Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.
@href (link-relationship attributes): Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.
@keyref: Specifies a key name that acts as a redirectable reference based on a key definition within a map. See The keyref attribute for information on using this attribute.
For HDITA, the equivalent of @keyref is @data-keyref
@scope (link-relationship attributes): Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.
See The scope attribute for detailed information on supported values and processing implications.
@type (link-relationship attributes): Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.

Examples

This section is non-normative.

This section contains examples of how the <xref> element can be used.

Example 1. Cross reference to another topic, without link text

The following code sample shows a cross reference to another topic. Link text is not provided. Processor typically use the topic title as the link text.

<p>Background information about DITA is provided in
<xref href="overview-of-dita.dita"/>.</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 the topic is used in different contexts.

Example 2. Cross references with link text specified

The following code sample shows a cross reference that specifies link text:

<p>While this set of tutorials gives several simple examples of
<xref keyref="markup-examples">common DITA features</xref>, a comprehensive
list of DITA features is available in the DITA specification
<xref keyref="dita-conformance">conformance clause</xref>.</p>

Example 3. Cross reference to an external ressource

The following code sample shows a cross reference to a web page:

<xref href="https://www.example.com/docview.wss?rs=757"
scope="external" format="html">Part number SSVNX5/>