DITA linking

URI-based addressing

URI-based links are described by the following attributes.

@href

The @href attribute specifies the URI of the resource that is being addressed.

@format

The @format attribute identifies the format of the resource being addressed. For example, references to DITA topics are identified with format="dita", whereas references to DITA maps use format="ditamap". References to other types of content should use other values for this attribute. By default, references to non-XML content use the extension of the URI in the @href attribute as the effective format.

@scope

The @scope attribute describes the closeness of the relationship between the current document and the target resource. Resources in the same information unit are considered "local"; resources in the same system as the referencing content but not part of the same information unit are considered "peer"; and resources outside the system, such as Web pages, are considered "external".

@type

The @type attribute is used on cross-references to describe the target of the reference. Most commonly, the @type attribute names the element type being referenced when format="dita".

These four attributes act as a unit, describing whatever link is established by the element that carries them.

The @format and @scope attributes are assigned default values based on the URI that is specified in the @href attribute. Thus they rarely need to be explicitly specified in most cases. However, they can be useful in many non-traditional linking scenarios or environments.

Indirect key-based addressing

DITA also supports indirect links and cross-references in which a DITA map assigns unique names, or keys, to the resources being referenced by the publication. This is done using <topicref> elements that specify the @keys attribute. Using the @keyref attribute, individual links, cross-references, and images then reference resources by their keys instead of their URIs . Links defined using @keyref thus allow context-specific linking behavior. That is, the links in a topic or map might resolve to one set of resources in one context, and a completely different set of resources in another, without the need for any modifications to the link markup.

When links are defined using @keyref, values for the four linking attributes described above are typically all specified (or given default values) on the key defining element.