How is content referenced from one topic to another in DITA?

Content can be referenced from one topic to another in DITA using cross-references, @conref, and @keyref attributes. These methods facilitate content reuse and linking within and across DITA documents.


Cross-references are used to create links or references from one location within a document to another location within the same document or to external documents. They provide a way to navigate between related content.

To create a cross-reference, the <xref> element is used. The href attribute of the <xref> element specifies the target topic or location using an ID or other reference. When rendered, cross-references generate clickable links.

Example: In a user manual, cross-references can be used to link from a section on “Troubleshooting” to a detailed explanation in another section of the same document.

@conref Attribute:

The @conref attribute allows content reuse by referencing and including the content of one element within another element, either within the same document or from external sources. It’s a powerful mechanism for modularizing and reusing content.

The @conref attribute is applied to an element, pointing to the source element that should be included. When the document is processed, the content of the referenced element is inserted into the target element.

Example: As shown in a previous example, the @conref attribute can be used to include a common introduction into multiple user guides.

@keyref Attribute:

The @keyref attribute is used for creating relationships between elements by referencing a unique identifier (key) defined elsewhere in the document or external resources. It enables content reuse and maintains consistency across documents.

The @keyref attribute references a specific key, linking the element to the content defined by the key. Changes to the content associated with the key are automatically reflected in all instances of @keyref.

Example: When multiple topics need to reference the same glossary term, the @keyref attribute can link these topics to a glossary term defined elsewhere, ensuring consistent terminology usage.