# DITA Best Practices : Add references to a DITA map

Created by Kelly Mankenberg, last modified on Oct 16, 2014

After you have created your DITA map, you can populate it with references to existing content, or content that is yet to be created.

## Referencing Existing Content

To reference content that has been previously created:

1. Within Oxygen, open the DITA map
   It should automatically open within the DITA Maps Manager pane.
2. On the DITA MAps Manager toolbar, click the Insert Reference button.
   or
   Right-click on the DITA map and select Append Child > Topic Reference.
   The Insert Reference dialog box is displayed.

3. Browse for and select the file you wish to include and click Insert and Close.

   Alternatively

   If you have more than one topic to insert, click the Insert button. then you can browse for another topic and click Insert again. When finished click Close.

4. The topic is inserted within the DITA map.

## Referencing Non-Existing Content

There are circumstances where you need to create a placeholder for content within your DITA map to content that does not yet exist.

Example

For this procedure, let's assume that we want to create a reference to a concept file that we are certain does not exist. Pay particular attention to the paths used in this procedure. InfoDev uses a logical hierarchy for storing the various types of content (topics, concepts, images, etc.).

To reference non-existing content:

1. On the DITA MAps Manager toolbar, click the Insert Reference button.
   or
   Right-click on the DITA map and select Append Child > Topic Reference.
   The Insert Reference dialog box is displayed.
2. Using the adopted standard for file type locations (concepts in the Concepts folder, etc), enter the path of the file you will eventually create in the URL field.
   The text entered in the example is : ../concepts/cmn_PreparingForInitialSetup.xml
   - The path construct of "../" indicates that the next item in the path (the concepts folder) is to be located at the same level of hierarchy as the map folder.
   - The concepts folder is the location where the file cmn_PreparingForInitialSetup.xml will be eventually created in.

3. When finished, click Insert and Close.
   The topic is inserted within the DITA map.

   Icon

   Notice the icon displayed with your reference.

   This indicates that the file does not exist and the reference is ready for file creation. Double-clicking the reference displays a prompt to create a new file in accordance with the path of the reference.

## Related articles

- Page:
  Add references to a DITA map
- Page:
  DITA map (ditamap)
- Page:
  Create a DITA map

## Attachments:

01.png (image/png)
02.png (image/png)
03.png (image/png)
04.png (image/png)
05.png (image/png)
06.png (image/png)
07.png (image/png)
08.png (image/png)