DITA Best Practices : Working with images

Created by Todd Stupnik, last modified on Jan 22, 2015

The following article provides best practices for using images within DITA topics.

Getting Started

Before continuing, note the following:

  • When using a screen capture tool (such as Snag-It, Adobe Photoshop Elements, Corel PhotoPaint), save your image as a .PNG file.
  • You should place your images locally at C:\Dev\Images.

Inserting images in oXygen 

  1. Either use the DITA>Insert>Images menu option or the Insert Image Reference button on the toolbar to locate your image.
  2. From the Choose Image dialog, click the folder icon to navigate to the C:\Dev\Images location.
  3. Select your image and click OK.

Using Images

  • Use the scale attribute to appropriately size your images; for PDF outputs, it is recommended that you experiment with a range of 30-50%; for webhelp, 80-100%. See Scale attribute below.
  • Many of our topics are used for both PDF and webhelp outputs; consider using the same image twice by applying a platform=print to one image and a platform=webhelp to the subsequent image. See Platform attribute below.
  • Typically, you should use a value of break when using the platform attribute. Use an inline value with screen icons; this places the images "inline," or at the same level, as sentences. See Platform attribute below.
  • For non-inline images, it is recommended that you place an image in a <p/> element where possible (in a task, you may be required to use an <info/> element within <steps><step><cmd></cmd></step></steps>). To display the image in its own block, use the image element independently (outside) of a paragraph element.

Scaling attribute

Scale specifies a percentage by which to scale the image in the absence of any specified image height or width; a value of 100 implies that the image should be presented at its intrinsic size. If a value has been specified for this image's height or width attribute (or both), the scale attribute is ignored.

WKFS Usage

The size of images within WKFS DITA documentation is modified only by the Scale Attribute. Do not use height or width; height and Width are valid DITA image attributes but hold no bearing on the WKFS transformation of the images.

Platform attribute

The platform attribute allows you to specify whether content applies to either PDF or webhelp outputs. You will need to create either print and webhelp values from the Profiling Settings option. For more information, see Creating attribute values.

Placement attribute

The placement of the image on the output page or screen is defined in the placement and align attributes. The placement attribute can be set to inline (placing the image inline with the text in the paragraph in which it is placed) or break (placing the image in its own block, with space above and below it). The align attribute has valid values of left, right, center and current. These values specify how the image will be aligned on the page or screen. The align attribute only has an effect if the placement is set to break.

Additional considerations

  • We typically have not utilized the align attribute, but you can use a center, left, or right value to place an image horizontally. For example, you may want to use a left value when placing images with numbered lists. By default, oXygen places the image centrally. NOTE: the align attribute only has an effect if the placement is set to break.
  • Consider also that while we have not typically used the alt attribute, this attribute can specify an alternate text for an image if the image cannot be displayed or if the user requires a screen reader.