Indirect linking with keys

Indirect linking and referencing is a way of specifying the target of a link or reference in the ditamap, rather than in the topic. The feature was introduced in DITA 1.2. This allows links to have different destinations, depending upon the ditamap in which the topic is used.

Indirection is an indirect method of linking, introduced in DITA 1.2. Instead of referring to the address of the resource, you refer to a key, which in turn refers to the address of the resource. As the key can be stored away from the topic in the ditamap, the same link or reference in a topic can point to different targets, depending upon the ditamap in which the topic is used.

Indirection opens up the opportunity to:

Key values are defined in a ditamap using the syntax keys="target URI". To refer to a key in a topic, usually inside a cross-reference (xref), term or image element, a keyref attribute is used instead of the direct href attribute. Indirection can also be used for content reference transclusion by using the conkeyref attribute in place of the direct conref attribute.

If the key referred to in a keyref attribute is not defined in the ditamap, the target reverts to the value of the href attribute, if defined.

For example, if the alpha key in the following cross-reference is not defined in the ditamap, the link will be created to abc.dita.
<xref keyref="alpha" href="abc.dita">Alpha</xref>
If the alpha key does exist, the href attribute will be ignored. (The keyref overrides the href.)

Schematic diagram showing how key and keyref attributes are used to redirect a link through indirection

Indirection schematic

Indirection has the effect of moving context from the topic to the map, which allows the topic to be re-used in more places.