The DITA content reference (conref) enables you to include the content of an element in one DITA document in another DITA document. When content is included from another document using a content reference, the included content replaces any content in the referencing element. An exception to this is the merging of attributes from the referencing and referenced elements, which is supported in the resolved document for styling and for document publishing.

Content references are based on elements, so the element you reference must be the same as the element containing the content reference. Content referenced can be viewed in a document, but cannot be edited. You must modify the original source of the reference in order to make changes. Arbortext Editor enables you to use the Resource Manager to locate content to reference in your documents. If a valid referencing element is not currently in your document, the Resource Manager automatically inserts a new, empty element into your document to be the target of the content reference.

Content references are defined by an attribute in your document type. The attribute is defined in the document type configuration file (.dcf) file. For DITA documents, the conref attribute is available on most DITA elements and is used as the content reference attribute.

In the content reference attribute, the string that references an element in a DITA topic has the following format:

[[path/]filename] is an optional reference to the file containing the reference. It may be an absolute or relative filename and may include path components. If the filename is not specified, the reference is assumed to be in the current document. If an absolute filename is not specified, the content reference is resolved using the DITA references path.

topic-id/element-id is a navigation path of ID attributes within a document. The topic-id is the identifier of the DITA topic element (or specialization of topic, such as concept, task, or reference), that contains the element being referenced. The element-id is the identifier of the element in that topic to be reused, such as a paragraph or list item. Both are required for content references within topics. If the element-id is omitted, the reference includes the entire topic. If both the topic-id and element-id are omitted, the reference is to the first topic in the file.

In the content reference attribute, the string that references an element in a DITA map has the following format:

For references to elements in DITA maps, only the element ID is necessary. If the mapelement-id is omitted, the reference is to the entire map. If the filename is omitted, the reference is to an element in the current document.

For example, assume a DITA paragraph element contains the following content reference:

The conref attribute indicates that the p element content should be included from the p element with the ID version, that is a child element of the topic element with the ID product, this is located in the releases.dita document. The releases.dita document being referenced would contain the following elements: