Edit online

Creating DITA Submaps

You can break up a large DITA map into more manageable pieces by creating submaps. A submap is simply a DITA map that is included by another DITA map. There is no separate markup for a submap.

For example, if you are creating a book, you might use one submap for each chapter of the book. If you are reusing a set of topics in multiple publications, you might collect them into a map and reuse the map as a submap in multiple other maps, rather than referencing the topics individually from the new maps.

You add a submap to a map the same way that you would add a new topic or insert an existing topic into a map, except you choose a map rather than a topic to create or add. When adding a submap to a map make sure that you use a <mapref> element or a <topicref> element with the @format attribute set to ditamap. In most cases, Oxygen XML Editor takes care of this for you.

Adding a Submap to a Map

To add a submap to a map:

  1. Right-click the place in the current map where you want to add the new submap.

  2. To insert the submap as a child of the selected node, select Append Child > New. To insert the submap as a sibling to the current node, select Insert After > New or Insert Before > New.

    Step Result: This opens a New DITA file dialog box that allows you to select the type of document and assists you with naming it.

  3. Select the type of map in one of the folders inside the DITA Map folder and give it a name (the file should have a .ditamap file extension).
  4. Click Create to insert the submap.
You can manage and move submaps the same as you would with topics. They can also be expanded and you can navigate their content in the DITA Maps Manager when the root (main) DITA map is open, but the references within those submaps are not editable, by default, unless you open the submap separately in its own tab.
Tip: If you want to be able to edit submaps when the main (root/parent) map is open in the DITA Maps Manager, go to Options > Preferences > DITA > Maps and select the Allow referenced submaps to be edited option.