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

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:
    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 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 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
    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 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. For more information, see the Adding an Image Using a Key Reference section.
    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.
    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:

  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.

Adding an Image Using a Key Reference

If you want to use a different version of the image depending on the situation (for example, screenshots for multiple platforms or types of output media), you can reference the image using a key reference:

  1. 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 multiple versions of a screenshot (one for Macintosh and another for the Windows version of your product).
  2. For each image, create a keydef element with the following structure:
    <keydef keys="image.test" href="img/test.png" format="png">
    Tip: You can easily create a keydef element that targets an image by using the Key Definition action from the Append Child or Insert After submenus.
  3. 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">
    Tip: If you create the keydef element using the Key Definition action, you can use the Profiling tab of the Insert Reference dialog box to easily add profiling attributes to the target.
  4. 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:
    <topicref href="images.ditamap" format="ditamap">
  5. To insert an image by key, insert an image element and use a keyref attribute to point to the image:
    <image keyref="image.test"/>
    Tip: You can also use the Keyref section of the Insert Image dialog box to insert a keyref attribute inside an image element.
    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.
  6. 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.