How are child maps and topics organized within a DITA map?

November 10, 2023
|By Bryan Tipper

Child maps and topics in a DITA map are organized using <mapref> elements and <topicref> elements, respectively. These elements help structure the map’s content by referencing other maps or topics and defining their order within the hierarchy.

Organizing with <mapref>

In a DITA map, child maps and topics are organized using specific elements, those being <mapref> and <topicref>.

<mapref>: Child Maps

Child maps, which are separate DITA maps, can be organized within a parent DITA map using <mapref> elements. A <mapref> element references a child map and includes attributes like href to specify the location of the child map. This allows for the hierarchical organization of maps within a parent map.

<topicref>: Topics

Topics are organized within a DITA map using <topicref> elements. Each <topicref> element references a DITA topic. Topics can be nested to create hierarchies, allowing for the organization of content into chapters, sections, and subsections within the map.

Example

A DITA map incorporates topics and other maps.


<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <title>Product Documentation</title>
  <mapref href="installation-guide.ditamap" />
  <topicref href="introduction.dita" />
  <topicref href="operation-guide.ditamap">
    <topicref href="operation-basics.dita" />
    <topicref href="operation-advanced.dita" />
  </topicref>
  <topicref href="troubleshooting.dita" />
</map>

In this example:

  • The <map> element defines the parent DITA map with the title “Product Documentation.”
  • A <mapref> element is used to reference a child map, “installation-guide.ditamap,” allowing the organization of a separate installation guide within the parent map.
  • Several <topicref> elements reference individual DITA topics, such as “introduction.dita” and “troubleshooting.dita.”
  • Nested <topicref> elements are used to create hierarchies within the map. For example, “operation-guide.ditamap” contains two child topics, “operation-basics.dita” and “operation-advanced.dita,” forming a section with subsections within the parent map.