Home
Graphics and figures
Image file formats
Where there is no strong reason to choose another image file format, you should use SVG or PNG file formats in DITA topics.
Image file management
Image files should be stored separately from topic files. Images can be re-used by referencing the same file name, by conref to an image element, or by conref to a fig element.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
Language and punctuation
Graphics and figures
- Figures and images
  Images are placed in topic content using the image element. The image element can stand alone, or can be contained within a figure (fig) element.
- Image file formats
  Where there is no strong reason to choose another image file format, you should use SVG or PNG file formats in DITA topics.
  - Image file management
    Image files should be stored separately from topic files. Images can be re-used by referencing the same file name, by conref to an image element, or by conref to a fig element.
  - Different graphics for different published media
    When a graphic needs to be presented differently for different output media, you should either include multiple versions of the graphics and use conditional processing to filter the required output, or use the keyref feature.
- Image alignment, placement, and sizing
  The align, placement, width, and height attributes of the image element are used to specify the placement and size of images when generated to an output delivery format.
- Images in titles
  Images in topic, figure, and other titles, while technically valid, should not be used.
- Callouts
  Callouts with keys, rather than text labels, should be used when identifying parts of an illustration.
- Localising graphics
  Where possible, graphics that include text should be managed in SVG format to simplify localisation.
- Multimedia in DITA topics
  The object element is used to embed multimedia in DITA topics.
- Figures containing tables
  Simple tables can be contained within figures instead of, or in addition to, images.
- Image maps
  The imagemap element is used to define image maps (hotspot graphics) in DITA topics.
- WAI compliance
  So that output from your DITA source meets accessibility responsibilities, you must include alternative text representations of all images in DITA content.
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Image file management

Image files should be stored separately from topic files. Images can be re-used by referencing the same file name, by conref to an image element, or by conref to a fig element.

Although there is no technical reason for taking this approach, you should store image files in a separate folder from content topics, for ease of organisation and file management. Use a consistent folder name for images, typically /images.

Image files should be re-used as required in different topics across your content repository. Simplistically, image file re-use can be a matter of referencing the same image file. An example of this type of re-use is:

<concept>
...
<img href="../images/ej25.png" width="480px" height="360px" />
...
</concept>

<task>
...
<img href="../images/ej25.png"  width="480px" height="360px" />
...
</task>

Like other DITA elements, image elements can be re-used through conref transclusion. An alternative method to simplistic re-use of image files is to re-use image elements by conref, as in the example:

<concept id="concept_engines">
...
<img id="img_ej25_engine" href="../images/ej25.png"
 width="480px" height="360px" />
...
</concept>

<task>
...
<img conref="#concept_engines/img_ej25_engine" href="-dita-use-conref-target" />
...
</task>

Because the href attribute of the image element is mandatory, you must set the value of the href attribute of the referencing image to -dita-use-conref-target.

The conref method has the advantage that attributes are also re-used, reducing some duplication of effort. However, if you deliberately want to have different attributes for different uses of the image, the simple file re-use method can be used.

If you are using figure (fig) structures instead of simple images, you can either conref the image element or the fig element. The method to choose will depend on whether you want to re-use the attributes and elements of the figure element.

In DITA 1.2, you can use the keyref feature to indirectly reference an image or figure, as an alternative to conref.