Adding Topics to a DITA Map

When you are working in DITA, there are several approaches that you can use to create topics and maps. You can start by first creating topics and then assembling your finished topics into one or more documents by creating one or more maps, or you can start by creating a map and then adding new topics to it as you work.

The topics-first approach is generally more appropriate if you intend to do a lot of content reuse, as it encourages you to think of each topic as an independent unit that can be combined with other topics in various ways. The map-first approach will be more familiar to you if you are used to creating books or manuals as a whole. Oxygen XML Editor supports both approaches.

A DITA map organizes content hierarchically, so you can add a topic as a child of the map root or as a child or sibling of any item already in the map. Therefore, the first step to adding a topic to a map is always to choose the place it will be inserted into the map.

Adding Existing Topics to a Map

At the XML-level, a topic is added to a map by adding a reference to the map that points to the topic. There are a variety of reference types that you can use. The default type is the topicref element. See the DITA documentation for the full range of reference elements and their uses. Oxygen XML Editor provides several tools for inserting reference elements into a map:

Using the Insert Reference Dialog Box

The Insert Reference dialog box allows you to create various reference types and configure the most commonly used attributes. You can open the Insert Reference dialog box with any of the following methods:

Right-click an item in the current map where you want to add the reference, select Append child or Insert After and select the type of reference to enter.
If the topic you want to add is currently open in the editor, you can right-click an item in the current map where you want to add the reference and select Reference to the currently edited file.
Selecting an item in the map and click the Insert Reference button from the DITA Maps Manager toolbar.
Select Insert Reference from the DITA Maps menu.

Dragging and Dropping a File into the DITA Maps Manager

You can add a topic to a DITA map by dragging and dropping the file into the DITA Maps Manager. You can drag and drop files from any of the following:

Your OS file system explorer
The Project view
The Open/Find Resource view

Adding topics this way will not open the Insert Reference dialog box, but you can adjust all the same properties by invoking the contextual menu from the topic and selecting Edit Properties.

Adding a New Topic to a Map

To add a new topic to a map:

Right-click the place in the current map where you want to add the new topic.
To insert the topic as a child of the selected node, select Append Child > New. To insert the topic as a sibling to the current node, select Insert After > New.
This opens a New file template dialog box that allows you to select the type of document and assists you with naming it.

Adding Multiple References to the Same Topic in a Map

Oxygen XML Editor allows you to add multiple references to the same topic in a DITA map. Whenever multiple references to the same topic are detected, an indicator will appear in the top-right corner of the Author mode editor that shows the number of times the topic is referenced in the DITA map. It also includes navigation arrows that allow you to jump to the next or previous reference.