home

ACST Content Standards

RealmMinistryPlatformPDSACSAccountingGivingConnectShepherdGrowth MethodGo MethodMissionInsiteGatherHeadMaster ChildcareTrust CenterData Governance and Business DocsACST Content Standards
RealmMinistryPlatformPDSACSAccountingGivingConnectShepherdGrowth MethodGo MethodMissionInsiteGatherHeadMaster ChildcareTrust CenterData Governance and Business DocsACST Content Standards

What would you like to know more about?

Show Contents

thumbnailACST Content Standards

Our Content Model

Images & Spacing When Published

Using these best practice for adding images will ensure the correct spacing when published. Learn more best practices for graphics and images here.

In DITA, images are typically not wrapped in a paragraph element for the following reasons:

  • Semantic Ambiguity - DITA is designed for semantic structure where each element has a meaning and purpose. The p element in DITA is intended for blocks of text that form a coherent paragraph. Images, while often related to text, are distinct media types and have their own semantic meaning. Wrapping an image inside a paragraph can blur the distinction between an image that's part of the narrative flow (like an icon in a sentence) and a separate, illustrative figure. This can complicate automated processing, translation, and accessibility efforts.
  • Layout and presentation control: DITA's strength lies in its ability to separate content from presentation. While the placement attribute on the image tag allows for some control (inline or on a new line), wrapping images in paragraphs can make fine-tuning layout across different output formats more complex. Images within figures (using the <fig> element) offer more robust control over layout and placement.
  • Accessibility challenges: Images placed within paragraphs, especially if they are large or complex, can create accessibility issues for screen readers and other assistive technologies. While alternative text (<alt>) is crucial for accessibility, placing images as standalone figures with descriptive captions provides a more structured and comprehensible experience for users with visual impairments.
  • Translation difficulties: When images are tightly coupled with the surrounding text within a paragraph, it can be harder for translators to separate and translate the text accurately without affecting the image or its placement.
  • Consistency and best practices: DITA best practices encourage using the <fig> element to encapsulate images that are meant to be standalone figures, including a title and a description. This promotes consistency across documentation and allows for easier management and reuse of images.
Attention: Although not represented in these examples, include descriptive alternative text (alt text) for each image to make the content accessible to users with disabilities. Alt text should convey the content or purpose of the image. See WCAG Compliance tips for writing alt text.

Wrap the Image in Figure Element

The DITA standards recommend wrapping images in the Figure element. We have not made a practice of this in our content model, but there are some advantages:
  1. It's efficient because the CSS manages the padding around the image without additional steps to add placement attributes.
  2. When you wrap the image in the figure element, the lightbox class is automatically added.
Note: Though not best practice, you do not have to add a figure title, which causes the image to match the majority of images in our existing content. (We should discuss this.)
<fig>
 <image "href="../images/darwin_library_of_congress.jpg">
  <alt>Photo of Charles Darwin: Library of Congress, Prints and
  Photographs Division, [reproduction number, LC-USZ61-104]</alt>
 <image>
</fig>

Aligning Images

We're currently experiencing a problem with the align property in attributes. To workaround this problem, you can add any of these outputclasses to an image: align-left, align-right, align-center.
Figure 1. Adding the Align OutputClass on an Image
This screenshot shows you where to insert the outputclass so that your image aligns as intended.

Images in Steps

You can include images in or after the </cmd> element. To insert an inline image in a command, select the placement attribute, then break.

To place an image right after a step, insert the </info> element, then insert the </image> or a figure element. If not using the figure element, select the placement attribute, then break.

Images in Tasks

View examples for including inline images, images with breaks, and images wrapped in figures within task elements.

With the exception of an inline image, to include images in </cmd> elements, you must insert the </info> element.
You can add an inline image or an image with a break, or an image wrapped in a figure in the context of a task.
  1. This is a step with an inline image. 
    <step>
    <cmd>This is a step with an inline image. <image href="../../../../acst-global-reuse/documents/Images/Google_Play_Store_Button.png" width="30px" placement="inline"/>
    </cmd>
 </step>
  2. This is an image inserted with </info></fig> elements after the commend.
    Figure 2. 
    
<cmd>This is an image inserted in a cmd with an figure. </cmd>
   <info>
      <fig><title/>
         <image href="../../../../acst-global-reuse/documents/Images/icon_other_mac.png"></image>
      </fig>
   </info>
  3. This is an image inserted after the paragraph with a break placement attribute. 


    
<cmd>This is an image inserted after the </cmd> element with a break placement attribute. </cmd>
     <info>
         <image href="../../../../acst-global-reuse/documents/Images/icon_other_maclaunchpad.png" placement="break"/>
     </info>

Last updated: March 3, 2026