Position and Frame Images

Images are a great way to enhance the text, whether to illustrate an idea, show rather than tell, or just help the reader connect with the text.

Out of the box, images and text behave like oil and water. Images don’t like to share space with text. They are kind of “pushy” about it. That’s why we focused on tuning the controls in the image macros so you can get the images and the text to flow together.

There are two approaches you can take when positioning your images:

  1. Named attributes

  2. Roles

Positioning attributes

AsciiDoc supports the align attribute on block images to align the image within the block (e.g., left, right or center). The named attribute float can be applied to both the block and inline image macros. Float pulls the image to one side of the page or the other and wraps block or inline content around it, respectively.

Here’s an example of a floating block image. The paragraphs or other blocks that follow the image will float up into the available space next to the image. The image will also be positioned horizontally in the center of the image block.

Example 1. A block image pulled to the right and centered within the block
image::tiger.png[Tiger,200,200,float="right",align="center"]

Here’s an example of a floating inline image. The image will float into the upper-right corner of the paragraph text.

Example 2. An inline image pulled to the right of the paragraph text
image:linux.png[Linux,150,150,float="right"]
You can find Linux everywhere these days!

When you use the named attributes, CSS gets added inline (e.g., style="float: left"). That’s bad practice because it can make the page harder to style when you want to customize the theme. It’s far better to use CSS classes for these sorts of things, which map to roles in AsciiDoc terminology.

Positioning roles

Here are the examples from above, now configured to use roles that map to CSS classes in the default Asciidoctor stylesheet:

Example 3. Block image macro using positioning roles
[.right.text-center]
image::tiger.png[Tiger,200,200]
Example 4. Inline image macro using positioning role
image:sunset.jpg[Sunset,150,150,role=right] What a beautiful sunset!

The following table lists all the roles available out of the box for positioning images.

Roles for positioning images
Float Align

Role

left

right

text-left

text-right

text-center

Block Image

Yes

Yes

Yes

Yes

Yes

Inline Image

Yes

Yes

No

No

No

Merely setting the float direction on an image is not sufficient for proper positioning. That’s because, by default, no space is left between the image and the text. To alleviate this problem, we’ve added sensible margins to images that use either the positioning named attributes or roles.

If you want to customize the image styles, perhaps to customize the margins, you can provide your own additions to the stylesheet (either by using your own stylesheet that builds on the default stylesheet or by adding the styles to a docinfo file).

The shorthand syntax for a role (.) can not yet be used with image styles.

Framing roles

It’s common to frame the image in a border to further offset it from the text. You can style any block or inline image to appear as a thumbnail using the thumb role (or th for short).

The thumb role doesn’t alter the dimensions of the image. For that, you need to assign the image a height and width.

Here’s a common example for adding an image to a blog post. The image floats to the right and is framed to make it stand out more from the text.

image:logo.png[role="related thumb right"] Here's text that will wrap around the image to the left.

Notice we added the related role to the image. This role isn’t technically required, but it gives the image semantic meaning.

Control the float

When you start floating images, you may discover that too much content is floating around the image. What you need is a way to clear the float. That is provided using another role, float-group.

Let’s assume that we’ve floated two images so that they are positioned next to each other and we want the next paragraph to appear below them.

[.left]
.Image A
image::a.png[A,240,180]

[.left]
.Image B
image::b.png[B,240,180,title=Image B]

Text below images.

When this example is converted, then viewed in a browser, the paragraph text appears to the right of the images. To fix this behavior, you just need to “group” the images together in a block with self-contained floats. Here’s how it’s done:

[.float-group]
--
[.left]
.Image A
image::a.png[A,240,180]

[.left]
.Image B
image::b.png[B,240,180]
--

Text below images.

This time, the text will appear below the images where we want it.