How is the @conref attribute used in DITA XML?

The @conref attribute in DITA XML is a powerful tool for content reuse and modular documentation. It stands for “conditional reference,” and it enables you to include or reference content from one topic to another, ensuring consistency and efficiency in your documentation. Here’s how the @conref attribute is used in DITA XML.

Content Reuse

One of the key functions of the @conref attribute is to reuse content across multiple topics. Instead of duplicating the same content in various places, you can create a single source and then reference it using @conref. This ensures that when you update the source content, all references to it automatically reflect the changes. It’s an effective way to maintain consistency in your documentation and reduce redundancy.

Conditional Inclusion

The @conref attribute also allows you to conditionally include or exclude content based on specific criteria. This is especially valuable when you need to tailor your documentation for different scenarios or audiences. By setting conditions, you can control which parts of the content are included in the final output. For example, you might have a single topic that includes information for both beginners and advanced users, and you can use conditions to deliver the relevant content to each group.


Here’s an example of how the @conref attribute is used to include content from one topic into another:

<topic id="topic1">
  <title>Getting Started</title>
  <p>This is the introductory content.</p>

<topic id="topic2">
  <title>Advanced Techniques</title>
  <p>These are advanced tips and tricks.</p>
  <p>For more basics, refer to <conref href="topic1.dita" />.</p>

In this example, the content from “topic1” is included in “topic2” using the @conref attribute. This way, you can maintain a single introductory topic and reference it from various places where it’s needed without duplicating the content.