Glossary Updates12 new terms added to the glossaries · October 2, 2026, 22:44 CEST
AI TechDocKnowledge

Glossary · Keys and reuse

DITA content reference (conref)

Also known as: conref, content reference, transclusion

In DITA, a content reference (conref) is a reuse mechanism in which an element, through the @conref attribute, pulls in the content of another element of the same type from another topic or map. When the document is processed, the referencing element is replaced by the referenced element.

  • DITA
  • Reuse

In one sentence

A DITA conref pulls the content of an element from another topic or map into the current one, so shared content is written only once.

Example

Every maintenance task contains <note conref="warehouse.dita#warehouse/unplug"/>, which is replaced by the warning “Disconnect the device from the power supply.”

Explained in context

Context cards connect this term with others to answer one question. Also in British English and German.

How it applies

  • Technical documentation: Conref is DITA's classic reuse mechanism. A warning, a standard step or a legal notice is written once in a source topic (often a dedicated “warehouse” topic) and pulled into every topic that needs it.
  • Addressing: The value is the address of the source element: file.dita#topicid/elementid. The referencing element is usually empty; if it has content, that content is replaced.
  • Ranges and pushing: @conrefend pulls a range of sibling elements (for example several steps); @conaction pushes content into another topic instead of pulling it (values pushbefore, pushafter, pushreplace and mark).
  • Compatibility: The referenced element must be of the same type as the referencing element or a specialization of it, and the result must be valid where it is inserted. The value -dita-use-conref-target lets a required attribute take its value from the source.
  • AI and retrieval: Resolve conrefs before indexing. An unresolved reference leaves an empty <note> — and a chunk without its safety warning.

Conref vs. conkeyref

A conref names the file directly. A conkeyref names a key and an element ID, so the map decides which source file is used.

In DITA markup

<!-- warehouse.dita -->
<topic id="warehouse">
  <title>Reusable warnings</title>
  <body><note id="unplug" type="warning">Disconnect the device from the power supply.</note></body>
</topic>

<!-- in a task -->
<note conref="warehouse.dita#warehouse/unplug"/>