Images

Images added to content can enhance user experience by providing visual feedback or examples. Heretto CCMS enables you to use common image formats, store them in the Content Library, and reuse them across your content set. The CCMS also enables you to add callouts and highlights (or annotations) to your images directly in the CCMS.

There are two DITA elements that are typically used to add images:

Figure (fig)

A block element (in outputs, it is typically rendered from a new line) that can contain other optional elements like title (title) or description (desc) as well as the image element (image). We recommend using this element for any image that you want to render from a new line in outputs, include a title or a description.

<fig>
	<title>V60 Pour-over Setup</title>
	<desc><p>A V60 pour-over setup with a paper filter in ceramic carafe.</p></desc>
	<image href="V60_Setup.png">
		<alt>V60 dripper on a ceramic carafe with a paper filter</alt>
	</image>
</fig>

Image (image)

An inline element (in outputs, it is typically rendered in line with text) that can contain the optional but recommended alternate text element (alt). We recommend using this element for any image you want to render in line with text. For example, an icon that represents a button in a user interface.

<image href="edit-button-icon.png">
	<alt>A pencil placed on top of a page</alt>
</image>

You can annotate your images directly in Heretto CCMS. Annotating an image means adding a color-coded callout or highlight to draw readers' attention to a specific detail. When you annotate an image directly in Heretto CCMS, you add a layer that contains the callout on top of the image without actually editing the image itself. This greatly increases the reusability of your images.

Important Considerations

By default, you can upload these image file types to the CCMS: .gif, .jpeg, .png, and .svg. It is possible to enable the import of additional valid file types. Contact your Customer Success Manager (CSM) for details.
Files with the .svg extension are XML files that can contain links to external resources like websites, or resources present in Heretto CCMS. If an .svg file contains a link that can't be resolved (because it points to a resource that doesn't exist in the CCMS), the file is highlighted as a file with broken links in the Content Library. That is expected behavior. Fixing or removing broken links in an .svg file removes the broken link indicator .
When using .svg files, be sure to set a width (and sometimes height) to control how they are presented in your outputs. You can set a width either directly in the .svg file or in the CCMS. Without set dimensions, SVGs may expand unpredictably, affecting layout and causing extra browser calculations. A defined width helps maintain aspect ratio with the viewBox attribute and ensures consistent scaling across devices. For responsiveness, you can use a fluid width like 100% with CSS, but an initial width adds predictability across different screens.
You can view and edit the XML code of .svg files in the CCMS by opening them in the Source Editor.
You can annotate any image that is supported by Heretto CCMS.
When you annotate an image in the CCMS, for example a .png file, the image element with the .png file is wrapped in an svg-container element. It doesn't convert the .png file into an .svg file.
When you annotate an image element that has the the scale attribute specified, the attribute is respected. When you annotate an image element that has the scale and width or height attributes specified, the scale attribute is respected and width or height are ignored.

Currently, the scale attribute is supported for standard and annotated images by Heretto Portal; it is not supported in PDF Generator.
Annotated images publish in PDFs generated with Heretto PDF Generator. They do not publish in outputs generated by DITA Open Toolkit (DITA-OT).
With an optional CCMS configuration, it is possible to define a custom color for annotation elements: highlight box and numbered callouts. This configuration ensures consistent annotation styling that follows your company branding and saves you time. Contact your CSM for details.
When you re-upload an image with an identical file name and extension to the same location in the CCMS, you can chose to overwrite it (default) or add as a separate copy. If you overwrite it, the new version of the image is automatically visible in every file the image is added to. To see the new image in your outputs, republish your content.

Annotations

You can add callouts or highlights to images directly in Heretto CCMS by using annotations. Your annotations are saved as a separate layer on top of your image, which means you can reuse an image and highlight a different area each time. Using annotations is an alternate and recommended approach to hardcoding callouts or highlights in images by using third-party tools.

When working with images, you often need to highlight a specific image area. Instead of uploading images edited in advance in a third-party tool, you can upload unedited images to Heretto CCMS and annotate them directly in the CCMS. We recommend annotating images in the CCMS as it:

Simplifies the process of annotating images
Ensures consistent look and feel
Enhances image reusability
Ensures text added to images (not recommended) is easily editable and translatable. Instead of adding text to images, we recommend using numbered callouts.

Note:

This functionality may not be available by default in Heretto CCMS. For more information, contact your Customer Success Manager.

The annotation types that we recommend are highlight box and numbered callouts. The highlight box enables you to add colored frames to areas you want to highlight. Numbered callouts enable you to highlight image areas with callouts and provide extra information in elements associated with the callouts. Those elements can be ordered list (ol) or steps (steps).

Note:

With an optional CCMS configuration, it is possible to define a custom color for annotation elements. For details, contact your CSM.

Figure 1. Highlight box added to an image wrapped in an SVG container

annotated image example — Figure 2. Numbered callouts added to an image wrapped in an SVG container

When you annotate an image, the image element is wrapped in an svg-container element, which enables you to add annotations over the image without modifying the image itself.

The Annotations interface enables you to:

Drag and drop ordered list items and steps from the Topic Preview pane on the right into the Image Preview pane on the left.
Note:
The callouts that you annotate images with update automatically as you add, move, or remove the ordered list item elements or step elements.
Move and rotate callouts in the Image Preview pane on the left.
Edit content in the Topic Preview pane on the right.
Figure 3. You can edit content directly in the annotations editor
Replace images by using the image context menu in the Topic Preview pane.
Figure 4. You can replace images directly in the annotations editor (blue highlight box in the pane on the right)

Insert an Image

Add images to your content to illustrate concepts and visualize processes and procedures. Images can contain attributes and properties, such as width, placement, or alignment.

In the Content Library, double-click a topic.
Place your cursor where you want to insert an image.
In the toolbar, select the image type you want to work with:
- To add a image in line with text (recommended only for small images, like icons), click Insert Image .
- To add an image that renders in a new line, click Insert Figure .

In the Select File window, select an image:

Option	Description
To insert an existing image,	navigate to the image, select it, and click Select.
To upload and insert a new image,	Click Upload a new file . In the Select files to upload window, click to choose files or drag and drop files. Click Upload Files. Select the uploaded image and click Select.

Optional: Set attributes for the image.
- To add alternate text (recommended), align the image, or change its width, click the image and use the context menu.
  
  Note:
  Based on the DITA 1.3 Standard, if you want to control the alignment of the image element, you must specify image alignment and set its placement attribute to break, which forces it to render in a new line.
- To set more attributes, open the Attributes tab for the image element and set your attributes there.
- To annotate the image, click Annotate Image and see Annotate an Image with Numbered Callouts and Annotate an Image with a Highlight Box. for details.

Change an Image

You can replace an image added to a topic with a different image by using the image context menu.

In the Content Library, double-click a topic.
Select an image and in the context menu, click Change.
In the Select Media window, navigate to and select a new image.
Click Select.

Remove an Image

You can remove an image added to a topic by using the image context menu.

In the Content Library, double-click a topic.
Select an image and in the context menu, click Remove.

Annotate an Image with a Highlight Box

You can annotate an image with a highlight box (or a frame) without modifying the image itself.

An image element is present in a topic. See Insert an Image.

Note:

This functionality may not be available by default in Heretto CCMS. For more information, contact your Customer Success Manager.

In the Content Library, double-click a topic.
Click the image that you want to annotate and from the image context menu, select Annotate Image.
In the annotation editor, select the Highlight Box option and highlight a desired area in the image. Click Close to save the changes.

Figure 5. A blue highlight box added to a user interface element

Your image now contains a highlight box that is saved in an additional layer added on top of your image. This means that the image itself has not changed and you can reuse it in other places.

You can edit annotated images at any point by clicking an image and selecting Edit Annotation from the context menu.

Annotate an Image with Numbered Callouts

You can add numbered callouts to images without modifying the images themselves. It is useful if you want to reuse the same image in different topics, or if you localize your content.

An image element is present in a topic. See Insert an Image.
An ordered list element or step elements are in a topic. See Insert an Element in a Topic.
Note:
This functionality may not be available by default in Heretto CCMS. For more information, contact your Customer Success Manager.

In the Content Library, double-click a topic.
Click the image that you want to annotate and from the image context menu, select Annotate Image.
From the Topic Preview pane on the right, drag and drop ordered list item elements or step elements into the Image Preview pane on the left.

Note:
The callouts that you annotate images with update automatically as you add, move, or remove the ordered list item elements or step elements.

Optional: Edit an annotation by doing any of the following:

Option	Description
To rotate the annotation,	do the following: Select the annotation. Click and hold . Move your mouse.
To combine multiple graphical elements,	do the following: Press and hold Shift. Click the elements that you want to combine. Right-click any selected element. Select Group.
To move a graphical element,	do the following: Click and hold the graphical element. Move your mouse.

Optional: In the Image Preview pane on the left, remove an annotation by right-clicking the annotation and selecting Delete from the context menu.
Once satisfied, click Close to save the changes.

Your image now contains callouts that are saved in an additional layer added on top of your image. This means that the image itself has not changed and you can reuse it in other places.

You can edit annotated images at any point by clicking an image and selecting Edit Annotation from the context menu.

Resize Canvas for an Annotated Image

You can adjust the canvas size of an annotated image in the Annotations interface. This is helpful when the canvas is larger than the image, affecting its positioning in the output. Resize the canvas to match or be smaller than the image.

In the Content Library, double-click a topic.
Select an annotated image and in the context menu, click Edit Annotation.
The Annotations interface opens.
Click SVG-Edit, and from the drop-down menu, select Document Properties.
Figure 6. Drop-down menu
In the Image Properties window, you can either:
- Manually enter the desired width and height (in pixels)
- Select a predefined size
Figure 7. Image Properties
Note:
Selecting an image size that is smaller than the actual graphic file may result in the image not appearing properly.
Click OK, click Close to save the changes.

Insert an Image Map

You can define linkable areas over an image by using image map elements.

In the Content Library, double-click a topic.
an image map element.
In the Select File window, choose an image and click Select.
The image map element is inserted. When you click the image, the Image Map context menu appears.
In the Image Map context menu, click Add to create the linkable area.
Add the shape, coordinates, and link values.
You can choose between rect, poly, and circle for as shapes. You can also choose default, which will mark the whole image as a linkable area. In that case, the coordinates should be left empty.

Click the image to see the defined linkable areas.

Under maintenance

Heretto Help

Images

Important Considerations

Annotations

Insert an Image

Change an Image

Remove an Image

Annotate an Image with a Highlight Box

Annotate an Image with Numbered Callouts

Resize Canvas for an Annotated Image

Insert an Image Map

Footer Section

Our Support Team is here to help