Content Key Referencing (conkeyref) is a mechanism in DITA that enables dynamic referencing and reuse of content based on specific key values. It allows retrieval and display of content from one location (source) into another (target) while specifying the content to retrieve using keys. This provides flexibility in content assembly and helps maintain consistency across documentation.

How Conkeyref Works

1. Key Definition: You define keys in your DITA documents, typically within the map or topicmeta elements. Keys are assigned unique values, such as IDs or labels. For example, the key “product-version” can be defined and assigned values such as “A,” “B,” or “C” to represent different product versions.
2. Key References: In DITA topics or maps, key references can be used to reference specific content based on these keys. Which key to reference is specified and which content should be retrieved is based on that key. Key references are typically written using the <conkeyref> element.
3. Content Retrieval: During the publishing or transformation process, DITA processing tools look for key references in your documents. They retrieve the content associated with the referenced key from the source topic and insert it into the target topic or output. This allows content reuse dynamically without duplication.

Example:

In this example, there is a set of documentation for different versions of a software product. The same set of installation instructions will be reused but customized based on the product version. This example shows one method of establishing a conkeyref:

Key Definition (in the DITA map or topicmeta):

<keydef keys="product-version" href="software-versions.dita"/>

Source Topic (software-versions.dita):

    <software-versions>
      <version keyref="product-version">A</version>
      <version keyref="product-version">B</version>
      <version keyref="product-version">C</version>
    </software-versions>
  

Target Topic (installation-instructions.dita):

    <installation-instructions>
      <title>Installation Instructions</title>
      <p>This document provides instructions for installing the software.</p>
      <conkeyref keyref="product-version"/>
    </installation-instructions>
  

In this example, the <conkeyref> element in the target topic references the “product-version” key, which is defined in the map. During output generation, the content from the source topic (software-versions.dita) corresponding to the specified product version is pulled into the target topic (installation-instructions.dita). This allows customizing the installation instructions for each product version while maintaining content reuse.