💡 Image and Caption formatting in asciidoc

[tiuweehan]

Hi all, the following is a short guide on how to resize and position images and captions nicely in asciidoc for both HTML and PDF.

I couldn't find any resources only so it took a while to figure out how to format the images for my PPP. Hopefully this might be helpful for some of you =)

Resizing Images

Step 1. The following is the standard way to embed images in asciidoc. By default, the width of the image in HTML will be 100% of the image size or 100% of the page width, whichever is smaller.

Example:

.This is my image
image::my_image.png[]

translates to

Step 2. To resize the image for HTML, use the width attribute of the image. You can adjust the size using either the percentage of page width (e.g. width=50%) or by absolute size of the image (e.g. width=10cm).

Example:

.This is my image
image::my_image.png[width=50%]

translates to

However, this might cause formatting issues when exporting to PDF, as seen below

Step 3. To adjust the width of an image in PDF, use the scaledwidth attribute instead. The scaledwidth attribute can be used together with the width attribute without causing formatting issues for HTML. However, do note that the scaledwidth attribute can only be adjusted by absolute size (e.g. scaledwidth=12cm)

Example:

.This is my image
image::my_image.png[width=50%, scaledwidth=12cm]

which translates to

Positioning images

Images like UML diagrams and captions should ideally be aligned to center. While it is possible to align images to the center in HTML, it is currently not possible to do so for captions in HTML. See @geshuming comments on this PR on how to do it for captions in HTML. However, it is still possible to do so in PDF.

Step 1. To align images (but not captions) in the center for both HTML and PDF,. use the align attribute.

Example:

.This is my image
image::my_image.png[align="center", width=50%, scaledwidth=12cm]

which translates to

Step 2. To align both images AND captions in the center for PDF, a few more steps are needed. Instead of using the PDF feature in Intellij, we have to install a command line version of asciidoctor-pdf from this link.

Step 3. By default, asciidoc-pdf aligns images and captions to the left, so we need to change this configuration. In the command line, execute the following command to find the directory where the ruby gems are stored

Example:

gem environment 

In this case, my gems are stored at /Users/tiuweehan/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0

Step 4. Find the directory where asciidoctor-pdf is stored. In this case, mine is stored at /(ruby gems directory)/gems/asciidoctor-pdf-1.5.0.beta.7/.

Step 5. Edit the configuration file at /(current directory)/data/theme/default-theme.yml.

Step 6. Change the value under caption > align from left to center (See line 132)

Example:

caption:
    align: center

Step 7. Now cd to the directory where the adoc file is and use asciidoctor-pdf to export the adoc file to PDF.

Example:

asciidoctor-pdf my_ascii_doc.adoc -o my_ascii_doc.pdf

The exported PDF should now be aligned nicely

[geshuming]

For positioning in HTML, I modified the asciidoctor.css file in /stylesheets to align the imageblocks.
The commit I made can be found here It was a small fix that didn't warrant installing applications/plugins, in my opinion.

it is currently not possible to do so for captions in HTML

My commit also aligns the caption, so for anyone wondering if you can, you can.

[tiuweehan]

For positioning in HTML, I modified the asciidoctor.css file in /stylesheets to align the imageblocks.
The commit I made can be found here It was a small fix that didn't warrant installing applications/plugins, in my opinion.

it is currently not possible to do so for captions in HTML

My commit also aligns the caption, so for anyone wondering if you can, you can.

This is even better!

Edit: Didn't manage to get this to work for me though :(

[geshuming]

Edit: Didn't manage to get this to work for me though :(

I don't think it shows up in the preview on the IDE, but it shows up for my team's site as well as deployment previews

[tiuweehan]

Edit: Didn't manage to get this to work for me though :(

I don't think it shows up in the preview on the IDE, but it shows up for my team's site as well as deployment previews

Oh you're right, I see it in my deployment previews now. But this method doesn't seem to work for exporting to pdf through IntelliJ though