Adding Topics to a DITA Map

When you are working in DITA, there are two approaches that you can use to create topics and maps. You can start by creating topics first, and then assemble 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 are intending 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 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 number of different reference types that you can use. The default is the topicref element. See the DITA documentation for the full range of reference elements and their uses. Oxygen XML Editor provides several different tools for inserting reference elements into a map:

Using the Insert Reference Dialog

The Insert Reference dialog allows you to create each of the different reference types and fill in the most commonly used attributes. You can open the Insert Reference dialog in a number of ways:

By right-clicking on an item in the current map where you want to add the reference, selecting Append child or Insert After, and selecting the type of reference to enter
If the topic you want to add is currently open in the editor, you can use the same procedure, but select Reference to the currently edited file...
By selecting an item in the map and clicking the Insert Reference button.
By selecting 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's file system explorer
The Project view
The Open/Find Resource view

Adding topics this way will not open the Insert Reference dialog, but you can adjust all the same properties by opening the Edit Reference dialog. Right-click on the reference you want to edit and choose Edit Properties....

Adding a New Topic to a Map

To add a new topic to a map:

Right-click on the place in the current map where you want to add the new topic.
Select either Append child or Insert After and then select New topic....