Overview
Instead of using explicit @href or @conref paths, DITA authors can define keys in maps and refer to them via @keyref. This allows the same topic set to be reused across multiple outputs simply by redefining key mappings.
Keyref Types
- Topic-level keyref: Reference to a topic defined by a key.
- Element-level keyref: Reference to a specific element within a topic defined by a key.
- Attribute-based keyref (conkeyref): Indirect reuse of element content via key.
Example 1: Topic-Level Keyref
Use Case: Linking to another topic indirectly through a key defined in a map.
topic.dita
<topic id="overview">
<title>Product Overview</title>
<body>
<p>See <xref keyref="product-intro"/> for more details.</p>
</body>
</topic>
|
map.ditamap
<map> <keydef keys="product-intro" href="intro_to_product.dita"/> </map> |
Syntax: keyref="key-name"
Example 2: Element-Level Keyref
Use Case: Linking to a specific element (for example, a section) within a topic defined by a key.
referring_topic.dita
<topic id="usage">
<title>Using the Product</title>
<body>
<p>Read the <xref keyref="product-doc/overview"/> section.</p>
</body>
</topic>
|
map.ditamap
<map> <keydef keys="product-doc" href="product_details.dita"/> </map>target (product_details.dita) <topic id="product_details">
<section id="overview">
<title>Product Overview</title>
</section>
</topic>
|
Syntax: keyref="key-name/element-id"
Example 3: Attribute-Based Keyref (conkeyref)
Use Case: Reusing specific content through a key reference, often for warnings or standard notes.
referring_topic.dita
<topic id="safety">
<title>Safety Guidelines</title>
<body>
<p conkeyref="common/texts/warning"/>
</body>
</topic>
|
map.ditamap
<map> <keydef keys="common" href="shared_texts.dita"/> </map>shared_texts.dita <topic id="texts"> <p id="warning">Handle with care.</p> </topic> |
Syntax: conkeyref="key-name/topic-id/element-id"
Summary
The @keyref mechanism separates content logic from file structure. Authors can redefine keys in different maps to point to different resources, supporting localization, product versioning, and modular content reuse without editing source topics.