DITA (Darwin Information Typing Architecture) offers a flexible way to manage and organize structured content, making it an ideal choice for creating and maintaining technical documentation. One of the key features of DITA is the ability to reference and include individual topics or other maps within a DITA map. This capability allows content authors to create modular, reusable, and well-structured documentation. Here, we’ll explore how to use <topicref> elements to achieve this in DITA XML.

Using <topicref> Elements

In DITA, you can use the <topicref> element to reference and include topics or maps within a DITA map. The <topicref> element specifies the location and attributes of the content to be included. To reference a DITA topic, you need to provide the path to the topic file using the href attribute. For maps, you use the mapref attribute. Additionally, you can set attributes such as format, scope, and processing-role to control how the content is processed.

Example:

Here’s an example of using <topicref> to include a DITA topic in a DITA map:

<map>
  <title>My Documentation Map</title>
  <topicref href="topic1.dita" format="dita" />
  <topicref href="topic2.dita" format="dita" />
  <mapref href="submap.ditamap" />
</map>

In this example, the DITA map includes two topics, “topic1.dita” and “topic2.dita,” using <topicref> elements. It also references a submap, “submap.ditamap,” using the <mapref> element. The format attribute specifies the format of the referenced content, which is “dita” in this case.