How are conref and conkeyref attributes defined in DITA?

November 10, 2023
|By Bryan Tipper

In DITA, the conref and conkeyref attributes are used to reference and reuse content from one topic in another. They enable single-sourcing and content reuse, which are essential for efficient technical documentation.

Conref Attribute:

Conref is short for “conditional reference.” It allows referencing content from one topic to another. The referenced content is not a direct copy but is linked, so any updates made in the source topic will reflect automatically in the topics where it’s referenced. The conref attribute syntax specifies the URI (Uniform Resource Identifier) to the source topic and the target element or range within the source topic to be included in the referencing topic.

Example:


        <topicref href="source-topic.dita">
          <topicmeta>
            <navtitle>Reusable Content</navtitle>
          </topicmeta>
          <navtitle>Chapter 1: Introduction</navtitle>
          <shortdesc conref="source-topic.dita#introduction/shortdesc"/>
          <body conref="source-topic.dita#introduction/content"/>
        </topicref>

In this example, the conref attribute is used to reference specific elements (shortdesc and body) from the source-topic.dita file. This allows content from the “Introduction” section of the source topic to be included in the current topic.

Conkeyref Attribute:

Conkeyref stands for “conditional key reference.” It enables conditional content reuse based on key references. Keys are used to mark specific content within a topic, and conkeyref references these keys to conditionally include or exclude content in the referencing topic. This is particularly useful when wanting to include or exclude content based on specific conditions, making documentation adaptable to various scenarios.

Example:

Source Topic (Original Content):


        <topic>
          <para>The sun is shining.</para>
          <para conkey="weather_rainy">Don't forget your umbrella.</para>
        </topic>

Target Topic (Conditional Reuse):


        <topic>
          <para>The weather is good.</para>
          <para conkeyref="weather_rainy">Don't forget your umbrella.</para>
        </topic>

In this example, the conkeyref attribute references the key “weather_rainy” to conditionally include the second paragraph based on the key’s presence in the source topic.