Search results

DITA: Images

You can add images in your content pretty much anywhere. It works like HTML except the tag is slightly different and you have to specify whether the image breaks the line or not.

Inserting an image

To insert an image, use the image tag and specify the placement attribute to set line wrapping.

<image href="images/sample.png" placement="break"><alt>Sample image</alt></image>

You can also choose placement="inline" if you're inserting an image in the line of your sentence (such as a button image) or if you want text to flow around your image.

The Open Toolkit renders images with a placement="break" attribute with two br tags before and after the image.

You can also choose an align attribute and select left, right, or center. The alt tags in the middle define the alt text for the image, which is what displays if a user's images are turned off.

Note that images won't automatically resize or automatically take on a border. However, you can set those properties in your webhelp CSS to accomplish this.

When you're writing a task, you can put images inside the cmd or the info tag.

If you want a caption to your images, add it like this:

<fig><title>Sample Image</title>
<image href="images/sample.png" placement="break"><alt>Sample image</alt></image>
</fig>

The caption will actually appear below the image in the Oxygen webhelp output.

Reusing images

If you reuse an image through the conref element, you must include the href attribute because this attribute is required. But the value for href is -dita-use-conref-target. 
<img conref="#concept_engines/img_ej25_engine" href="-dita-use-conref-target" />

Referring to specific figures

If you want to refer to an image with a specific figure caption, you can use cross reference. 
<p>See <xref href="#concept_lcw_fkl_q4/image1" type="fig">Oxygen Sample Webhelp</xref> for details.</p>

<fig id="image1">
    <title>Oxygen Sample Webhelp</title>
   <image href="oxygen.png" placement="break"/>
</fig>

The output will say "See Oxygen Sample Webhelp for details." With the webhelp, the reference will link to the image. The image itself won't have a figure number below it. With PDF, there will be a figure number below it.

If you want to use conref to manually pull in the image title, you can do so like this: 
<p>See <xref href="#concept_lcw_fkl_q4/image1" type="fig"><ph conref="testfile.dita#concept_lcw_fkl_q4/image1_title"/></xref> for details.</p>


   <fig id="image1" frame="all">

    <title><ph id="image1_title">Oxygen Sample Webhelp</ph></title>
   <image href="oxygen.png" placement="break" scalefit="yes"/>
   </fig>

Image format

It's recommended that you use the SVG format for images because this format allows you to add callouts that you can later edit and extract for translation.

Other parameters

If you want a border around your image and caption, use the frame="all" attribute. If you want your image to be scaled to its container size, use scalefit. You can also specify a width.

<fig id="image1" frame="all">
    <title>Oxygen Sample Webhelp</title>
   <image href="oxygen.png" placement="break" scalefit="yes" width="700"/>
</fig>

However, I think it would be wiser to use max-width on images in your webhelp stylesheet.

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2023 Tom Johnson