Adding Images to a DITA Topic

There are several ways to add images to a DITA topic, depending on if you want to create a figure element (with a title and caption) or just insert an image inline, and if you want to use different versions of a graphic in various different situations. For instance, you might want to use a specific image for each different product version or output media.

Adding an Image Inline

Use the following procedure to add an image inline:

Place the caret in the position you want the graphic to be inserted.
Select the Insert Image Reference action. The Insert Image dialog box appears.
Figure: The Insert Image Dialog Box
Configure the options in this dialog box and click Insert.
The Insert Image dialog box includes the following options for inserting images into a DITA document:
URL
Inserts an image element with an href attribute. You can type the URL of the image you want to insert or use the Browse drop-down list to select an image using one of the following options:
- Browse for local file - Displays the Open dialog box to select a local file.
- Browse for remote file - Displays the Open URL dialog box to select a remote file.
- Browse for archived file - Opens the Archive Browser to select a file from an archive.
- Browse Data Source Explorer - Opens the Data Source Explorer to select a file from a connected data source.
- Search for file - Displays the Find Resource dialog box to search for a file.
Keyref

Opens the Insert Key Reference dialog box that presents the list of keys available in the current DITA Map. Use this dialog box to insert an image element with a keyref attribute. All keys that are presented in the dialog box are gathered from the root map of the current DITA map. Elements that have the keyref attribute set are displayed as links.
Note: If the DITA map is not opened in the DITA Maps Manager view, the Insert Key Reference dialog box does not display any keys.

Figure title

Use this text box to insert a title and image element inside a fig element.

Alternate text

Use this text box to insert an alt element inside the image element.

Size

Use this section to configure the Width and Height of the image, or Scale the image. Specifying a value in these options inserts a width, height, and scale attribute, respectively.

Layout

Use the options in this section to insert placement and align attributes into the image element.

Adding an Image in a Figure Element

To add an image in a figure:

Add a fig element to your document at the appropriate place.
Add a title and/or desc element to the fig element, according to your needs.
Add an image element to the fig element.

Note: The fig element has a number of other child elements that may be appropriate to your content. See the DITA documentation for complete information on the fig element.

Note: The order in which the image, title, and desc content are presented in output is determined by the output transformation. If you want to change how they are output, you may have to modify the output transformation, rather than your source content.

Adding an Image Using a Key Reference

If you want to use a different version of the image in various situations, such as screenshots for multiple platforms or different formats for various types of output media, you can reference the image using a key reference:

Create a DITA map to hold your image keys. You can create one map for each use or create a single map and profile the key definitions for multiple uses. For instance, you might create one map of images to be used in PDF and one for images to be used in Web output, or you might use the platform profiling attribute to manage different versions of a screenshot (one for Macintosh and another for the Windows version of your product).
For each image, create a keydef element with the following structure:
```
<keydef keys="image.test" href="img/test.png" format="png">
```

If you are using profiling, add the alternative keydef elements and the appropriate profiling attributes:

<keydef keys="image.test" href="img/win/test.png" platform="windows" format="png">
<keydef keys="image.test" href="img/mac/test.png" platform="mac" format="png">

If you are using separate maps, repeat in each map. For instance, if you are using a separate map for images in PDF output, add a topic ref to that map like this:
```
<keydef keys="image.test" href="img/test.eps"  format="eps">
```
To insert an image by key, insert an image element and use a keyref attribute to point to the image:
```
<image keyref="image.test"/>
```
Oxygen XML Editor displays the image in Author mode. Which image is displayed depends on the current profiling set that is applied and which root map is being used to resolve references.
Configure your build so that the appropriate image map is included for each output type and/or the appropriate profiling conditions are applied to each output.

Note: You can also use the

Insert Image Reference action to insert a keyref attribute inside an image element.