Embedded (or nested) ditamaps

The technique of using embedded, or nested, ditamaps can make it easier to manage documents by separating complex collections of topics into a number of smaller, simpler collections.

The topicref elements in a ditamap usually reference a topic. However, they can also reference ditamaps, which opens up the opportunity for having embedded (or nested) maps.

A reference to a ditamap differs from a reference to a topic in having a format attribute of ditamap. The syntax of a reference to a ditamap is:
<topicref 
  format="ditamap"
   href="engine/ej25.ditamap"
   navtitle="2.5 Litre Engine">
</topicref>
Figure 1 illustrates how ditamaps (such as the Storing Data and Widget Specifications ditamaps) can be nested within another ditamap (in this case, the Widget User Guide). Nesting can continue down to many levels deep. And ditamaps can be nested within many other ditamaps.

Diagram showing principle of re-used, embedded (or nested) ditamaps

Re-used, embedded (or nested) ditamaps

Nesting ditamaps is a useful tool in permitting content re-use and authoring efficiency.

The term mapref is sometimes used as shorthand for a topicref with a format attribute of ditamap. Until DITA 1.2, there was no DITA element of mapref, but 1.2 introduced a mapref as a convenience element identical in functionality to topicref with a format attribute of ditamap.