xref
Typically, it is best to restrict yourself to linking to reference topics where the content of the target is clear from the <xref>'s text, for example API names and their descriptions. With other information types, it may be less clear to the user whether they should follow the link, and often they will, thereby missing important information in following paragraphs. Therefore, it is a good idea to use links at the end of the topic, in the <related-links> element, wherever possible, rather than linking from within body content using <xref>. Links at the end of a topic can also be managed from outside the topic, using DITA maps. The DITA map method allows allows topics to be quickly integrated into new contexts without breaking links.
Cross references that link to elements in other topics should use key-based addressing (keyref) in order to make it possible to have the cross-reference point to different topics in the context of different top-level maps. Cross references that use only direct URI-based addressing (href) to point to other topics create dependencies such that if the topic with the cross-reference is included in a given map, the target topic must also be included or the cross-reference will not 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 used in because it is up to each different map to bind the key used by the cross-reference to the appropriate target.
Note
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 <figure> element, not the <title> element within the <figure> element. Output processing should determine whether the text of the object's title element is used when rendering the cross-reference.
Contains
Note
| Doctype | Content model |
|---|---|
| topic (base), map (base), classifyMap, subjectScheme, learningAssessment, learningBookmap, learningContent, learningMap, learningOverview, learningPlan, learningSummary | ( text data or boolean or keyword or ph or b or i or sup or sub or tt or u or q or term or tm or state or data or data-about or foreign or unknown or image or desc) (any number) |
| topic (technical content), map (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap | ( text data or boolean or keyword or apiname or option or parmname or cmdname or msgnum or varname or wintitle or ph or b or i or sup or sub or tt or u or codeph or synph or filepath or msgph or systemoutput or userinput or menucascade or uicontrol or q or term or abbreviated-form or tm or state or data or data-about or foreign or unknown or image or desc) (any number) |
| machineryTask | ( text data or boolean or keyword or wintitle or ph or b or i or sup or sub or tt or u or menucascade or uicontrol or q or term or tm or state or data or data-about or foreign or unknown or image or desc) (any number) |
Contained by
Inheritance
- topic/xref
Examples
Here's an example of a cross-reference to another topic; that topic's title will be used as the link text.
<p>Background information about DITA is provided in the topic entitled <xref href="whatsdita.dita#tmmdita"></xref>.</p>
Here's an example of a cross-reference to another topic; the supplied text will be used as the link text:
<p><xref href="whatsdita.dita#tmmdita">Background information about DITA</xref> is provided free of charge.</p>
If you are linking to an element inside of a topic, you should use the following format in the href attribute:
filename.dita#topicid/elementid
If you are linking within the same file, you can leave off the "filename.dita" part. So, for a section with the ID "mysection", you should use:
#topicid/mysection
For a list item within that section, assuming the item has an ID of "mylist", use
#topicid/mylist
See DITA addressing for details on using URI references and 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:
http://www.example.com/docview.wss?rs=757&context=SSVNX5
When used in an href attribute, the ampersand must be entered as & as shown here:
<xref href="http://www.example.com/docview.wss?rs=757&context=SSVNX5" scope="external">Part number SSVNX5</xref>
Attributes
| Name | Description | Data Type | Default Value | Required? |
|---|---|---|---|---|
| href | Provides a reference to a resource. See The href attribute for detailed information on supported values and processing implications. | CDATA | #IMPLIED | No |
| type | Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications. | CDATA | #IMPLIED | No |
| format | The format attribute identifies the format of the resource being referenced. See The format attribute for details on supported values. | CDATA | #IMPLIED | No |
| scope | The scope attribute identifies the closeness of the relationship between the current document and the target resource. See The scope attribute for more information on values. | (local | peer | external | -dita-use-conref-target) | #IMPLIED | No |
| univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups) | A set of related attributes, described in univ-atts attribute group | |||
| global-atts attribute group (xtrf, xtrc) | A set of related attributes, described in global-atts attribute group | |||
| class, outputclass, keyref | Keyref provides a redirectable reference based on a key defined within a map. See The keyref attribute for information on using this attribute. Class and outputclass are described in Other common DITA attributes |