Edit online

Images are an important part of a publication.
Note: You can use raster image formats (such as PNG or JPEG), but it is best to use vector images (such as SVG or PDF). They scale very well and produce better results when printed. In addition, the text from these images is searchable and can be selected (if the glyphs have not been converted to shapes) in the PDF viewer.

Edit online

Image properties are defined in [PLUGIN_DIR]css/print/p-figures-images.css.

  *[class ~= "topic/image"] {
        prince-image-resolution: 120dpi;
        -ah-image-resolution: 120dpi;
        image-resolution: 120dpi;
        /* The US-letter page size minus page margins. See p-page-size.css for the current page size. */
        max-width: 6.5in;         
    }

Edit online

Sometimes the images may be too big for the page. The built-in CSS rules specify a maximum size for images, limiting to the width of the parent block. But if the parent block is itself too wide and bleeds out of page, you might consider specifying a length.

In your customization CSS, add the following snippet:

  *[class ~= "topic/image"] {
    ...
        /* The US-letter page size minus page margins. See p-page-size.css for the current page size. */
        max-width: 6.5in;         
    }

Edit online

This is a good technique to change the size of all raster images from your documentation. This will not work for vector images, such as PDF or SVG. If the images (PNG, for example) contain the image resolution in their metadata, this will be taken into account. For all other images, the default resolution is 120dpi.

Note: Instead of using @width and @height, it is recommended that you use images that fit the page dimensions. Then you could fine-tune the images in the output using the image-resolution property (see below). This will help to prevent image rendering issues (for example, a multiple format output or a replaced image in the source file).

If the default resolution is not good (suppose you need a higher pixel density of 300dpi), you can change it by adding the following in your customization CSS:

*[class ~= "topic/image"] {
        prince-image-resolution: 300dpi;
        -ah-image-resolution: 300dpi;
        image-resolution: 300dpi;
}    

Edit online

Very wide images may bleed out of the page. One solution for this is to use landscape pages for these wide images.

In your customization CSS, add:

*[class~="topic/image"][outputclass='land'] {
    page: landscape-page;
}

Setting the attribute @outputclass = 'land' on the table element will force the table on a new landscape page.

Another solution is to set an @outputclass attribute on the image, then create a rule that matches it, and associate a landscape page for it.

Edit online

If you need to align text and an image side by side, you can use the following technique:

  1. Organize your text and image under a <div> element like this:
    ...
     <div outputclass="side-by-side">
          <p> This will be in the left side, the next figure in the right. </p>
          <fig>
            <image href="cactus.jpeg"/>
          </fig>
     </div>
    ...
    Note: You can use the @outputclass attribute to mark the <div> elements that have this special layout.
  2. In your customization CSS, add:
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/p"] {
      display:inline-block;
      width: 45%;
    }  
    
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"] {
      display:inline-block;
      width: 45%;
    }  
    
    The image should fill the entire width of the parent <fig> element:
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"]  > *[class ~= "topic/image"] {
      width:100%;
    }
    By default, the bottom of the image is on the same line as the text baseline. If you want the text and the image to be aligned at the top, add these lines:
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/p"] {
      vertical-align:top;
    }  
    
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"] {  
      vertical-align:top;
      font-size:0pt;  
    }  
    Note: The font-size:0pt is needed to remove the font ascent and descent around the image rectangle.

Edit online

It is common to have text and images mixed together in a :before or :after pseudo-element. For example, for notes you may have both artwork and text:

*[class ~= "topic/note"]::before {
    content: url('note.png') "Some text";
}

If you want to change the size of the image, you have two options:

  • Use the image-resolution CSS property:
    *[class ~= "topic/note"] {
        image-resolution:300dpi;
    }
  • Separate the image from the text and apply the width and height CSS properties only on the image, using the width and height properties. You could use multiple :before pseudo-elements for that, considering that the farthest content presented before the actual content of an element is matched by the :before with the highest number in the brackets:
*[class ~= "topic/note"]:before(2) {
    content: url('note.png') ;
    width:0.5in;
}

*[class ~= "topic/note"]:before(1) {
    content: "Some text";
}

Edit online

DITA defines a @placement attribute for the <image> elements. The implicit value is inline. Suppose that you need to center the images that have the placement set to break (for example, they are not on the same line with other content and the images from the <fig> element).

In your customization CSS, add:

*[class ~= "topic/fig"] {
  text-align:center;
}

/* Other images, with break placement. */
*[class ~= "topic/image"][placement='break']{
  display:block;
  text-align:center;
}

/* 
 Scaled images are getting a computed width attribute, so we can use the auto margins.
 Auto margins function only if the block they apply to has a width. 
*/
*[class ~= "topic/image"][placement='break'][width] {
  margin-left:auto;
  margin-right:auto;
  border: 2pt solid red; 
}

Edit online

Note: This topic is applicable for the DITA Map PDF - based on HTML5 & CSS DITA PDF - based on HTML5 & CSS transformation types.
There are cases when you need to change the aspect of the figure counter that is shown before the figure titles. By default, the figure titles are formatted like this:
Figure NN. Lore Ipsum Title

NN is the number of the figure that starts being counted from the beginning of the publication.

One use-case is to have the NN counter be incremented only within one chapter (for example, the first chapter contains "Figure 1" and "Figure 2", and the second chapter starts over with "Figure 1" instead of incrementing to "Figure 3").

You should reset the figure counter on each topic marked as chapter, then hide the label from the figure <figcaption> (this is an HTML element generated by the XSL transformation), and create another label using a :before selector on the <figcaption>.

*[class ~= "topic/topic"][is-chapter] {
  counter-reset: figcount;
}

.fig--title-label{
  display:none;
}

*[class ~= "topic/fig"] > .figcap:before{
  /* Add more styling or change the content if needed */
  content: "Figure " counter(figcount) ". ";
  counter-increment: figcount;
}

Edit online

If your images are not accessible, you may receive an error message in the transformation console like this:

Image not found. URI:file:/path/to/my/image

This is usually because they are in a folder that is not in the folder subtree of the transformed map or topic.

To solve this, you can set the following transformation parameter: fix.external.refs.com.oxygenxml=true.