How does conref work in DITA for reusing content?

November 10, 2023
|By Bryan Tipper

DITA utilizes a robust mechanism known as “conref” (content referencing) for the purpose of content reuse. Conref enables referencing and reusing content from one topic in another, ensuring consistency, modularity, and simplified maintenance within structured documentation.

Using conref for content reuse involves:

  1. Reusable Content: Conref is employed to refer to reusable content within DITA topics or across distinct topics. This content can encompass text, images, tables, or various other structured elements.
  2. Insertion Point: In the target topic where content reuse is desired, an insertion point is defined through the <conref> element. This serves as the location for inserting the referenced content.
  3. Referencing the Source: For referencing the source content, the conref attribute is employed within the <conref> element. This attribute contains a path leading to the source content intended for reuse. This path points to the specific element within the source topic to be reused.
  4. Target Element Matching: The referenced content is matched with a target element located within the source topic. It is essential that these elements possess similar structures, meaning that the target element within the insertion point must align with the structure of the source element.

Example

A product name is utilized in multiple topics. Conref can be employed for its reuse as follows:

Source Topic (source.dita):


        <p id="product-name">Product X</p>

Target Topic (target.dita):


        <topic>
          <title>Utilizing Product X</title>
          <body>
            <p>Our product, <conref href="source.dita#product-name"/> is ideal for your requirements.</p>
          </body>
        </topic>

In this example, the <conref> element within the target topic references the product-name paragraph from the source topic. When generating output, “Product X” from the source will be inserted into the target topic.