DITA Conref: Reusing XML Paragraphs

DITA content referencing, commonly known as conref, is a core mechanism in Darwin Information Typing Architecture that allows technical writers to single-source content components across multiple documents. By pointing an empty element in a target document to an identical, fully authored element in a central source topic, conref ensures consistent paragraph reuse across varied publications. This article explains how the conref mechanism functions, its underlying syntax, and how it streamlines content maintenance during the publishing process.

The Mechanism of Content Referencing

The conref mechanism operates by establishing an explicit link between a source XML element and a target XML element of the exact same type. Instead of copying and pasting identical text—such as legal notices, safety warnings, or standard product descriptions—writers store the text once in a dedicated source file (often called a warehouse or reuse topic).

When another document requires that exact paragraph, the writer inserts an empty tag matching the element type and assigns it a conref attribute that points to the unique identifier of the source paragraph.

XML Syntax and Resolution

To execute a paragraph-level content reference, both the source topic and the specific source paragraph must have unique id attributes.

Source Paragraph Definition

In the source topic (warehouse.dita), the paragraph is assigned an ID:

<topic id="reuse_warehouse">
  <title>Reusable Content Warehouse</title>
  <body>
    <p id="standard_warranty">All products include a standard one-year limited hardware warranty covering manufacturing defects.</p>
  </body>
</topic>

Referencing the Paragraph

In the target topic (user_guide.dita), an empty paragraph references the source using the relative path, topic ID, and element ID:

<topic id="user_guide">
  <title>Product Maintenance</title>
  <body>
    <p conref="warehouse.dita#reuse_warehouse/standard_warranty"/>
  </body>
</topic>

During the publishing build process (typically managed by the DITA Open Toolkit), the processor resolves the reference by replacing the empty target element and its conref attribute with the full content of the source <p> element.

Rules for Valid Implementation

For a conref to function correctly, the XML parser enforces strict structural rules:

Element Matching: The target element must match the source element type. A <p> element can only reference another <p> element; it cannot reference a <li> or a <note>.
Unique Identification: Both the enclosing topic and the specific XML element must possess valid id attributes.
Valid Path Resolution: The file path specified in the conref attribute must resolve correctly at the time of publication.

Operational Advantages Across Publications

Implementing conref for identical paragraphs yields several practical benefits across an organization’s content ecosystem:

Single-Source Maintenance: Modifying a shared paragraph in the source file automatically updates every publication that references it upon the next build.
Content Consistency: Eliminates minor discrepancies, typos, and phrasing variations between different manuals or product versions.
Reduced Translation Costs: Because the source paragraph is only authored once, it only needs to be translated once, significantly lowering localization expenses across global document sets.
Separation of Content and Assembly: Content creators can focus on updating standardized text blocks without needing to manually edit dozens of independent deliverables.