Glossary · Keys and reuse

DITA content key reference (conkeyref)

Also known as: conkeyref, content key reference

In DITA, a content key reference (conkeyref) is a content reference that addresses its source through a key instead of a file name: the @conkeyref attribute names a key and, optionally, the ID of an element within the resource that the key points to.

DITA
Reuse

In one sentence

A DITA conkeyref is a content reference addressed through a key: the map decides which file the reused content comes from.

Example

<note conkeyref="warnings/unplug"/> pulls the warning from warehouse-eu.dita in the European manual and from warehouse-us.dita in the US manual.

How it applies

Technical documentation: Conkeyref combines reuse with indirection. The topic names a key and an element ID; the map binds the key to a file. Two maps can bind the same key to different warehouse topics — for example one per product line or per market — and the same topic pulls in different content in each.
Fallback: If the key is not defined, processors fall back to the @conref value on the same element, if there is one.
AI and retrieval: Because the resolved content depends on the map, the same source topic can produce different text in different deliverables. Index resolved output, and record which map produced it.

Conkeyref vs. conref

A conref is fixed to one file. A conkeyref follows the key, so moving or swapping the source file only requires changing the key definition.

In DITA markup

<!-- in the map -->
<keydef keys="warnings" href="warehouse-eu.dita"/>

<!-- in a task -->
<note conkeyref="warnings/unplug"/>