Can conref be used to reference content from other topics?

November 10, 2023
|By Bryan Tipper

Conref (content referencing) in DITA enables the referencing of content from one DITA topic in another, facilitating content reuse across different topics within structured documentation.

Using conref involves:

  1. Content Reuse: Conref permits the incorporation of content from one DITA topic into another, including text, images, tables, or other structured elements.
  2. Insertion Point: Within the target DITA topic, where content reuse is desired, an insertion point is created by employing the <conref> element. This specifies the location for inserting the referenced content.
  3. Referencing the Source: Referencing the source content is accomplished using the <conref> attribute within the <conref> element. This attribute points to the path of the source content for reuse, indicating a specific element within the source topic.
  4. Target Element Matching: The referenced content should correspond to a target element in the source DITA topic. This entails ensuring that the structure of the target element within the insertion point aligns with the structure of the source element.

Example

A common warning message needs to be reused across multiple topics in a DITA documentation set:

Source Topic (source.dita):


        <warning id="common-warning">Caution: This action cannot be undone.</warning>

Target Topic (target.dita):


        <topic>
          <title>Backup Procedure</title>
          <body>
            <p>Before proceeding, be aware of the following:<conref href="source.dita#common-warning"/></p>
          </body>
        </topic>

In this example, the <conref> element in the target topic references the common-warning warning message from the source topic. During output generation, the warning message is inserted into the target topic.