Adding Images in DITA Topics

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), just insert an image inline, or if you want to use multiple versions of a graphic depending on the situation. For instance, you might want to use a specific image for each different product version or output media.

Adding an Image Inline with the Insert Image Dialog Box

Use the following procedure to add an image inline:

  1. Place the cursor in the position you want the graphic to be inserted.
  2. Select the Insert Image action. The Insert Image dialog box appears.

    Figure: Insert Image Dialog Box

  3. 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:
    Use this option to specify a URL for the image. It will insert the URL as the value of an href attribute inside an image element. You can type the URL of the image you want to insert or use the Browse drop-down menu 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 workspace - Opens a file browser dialog box that allows you to select a file from the local workspace.
    • Browse for remote file - Displays the Open using FTP/SFTP 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.
    You can use the Choose Key Reference button to open the Choose Key dialog box that presents the list of keys available in the selected root map. Use this dialog box to insert the selected key as the value of a keyref attribute inside an image element. 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 your defined keys are not listed in this dialog box, it is most likely trying to gather keys from the wrong root map. You can change the root map by using the Change Root Map link.
    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.
    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.
    Use the options in this section to insert placement and align attributes into the image element.

Adding an Image Inline with Drag/Drop (or Copy/Paste) Actions

You can drag images from your system explorer or the Navigator view and drop them into a DITA document (or copy and paste). This will insert the path of the image file as the value of the href attribute in a DITA image element:
<image href="../images/image_file.png"/>
Tip: To replace an image, just drag and drop a new image over the existing one. Oxygen XML Editor plugin will automatically update the reference to the new image.

Adding an Image in a Figure Element

To add an image in a figure:

  1. Add a fig element to your document at the appropriate place.
  2. Add a title and/or desc element to the fig element, according to your needs.
  3. 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 about 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.