Images

Inserting Images

The eye eats too. That’s why images and other visualizations add tremendous value to your texts. You can insert them in adoc Studio with just a few clicks.

You insert images using the classic methods:

  • Drag & Drop: Drag the image directly to the desired text position.

  • Copy & Paste: Copy the image with ⌘+C and paste it at the desired location with ⌘+V.

image editor

All images are saved in the media folder. The folder can be viewed in the sidebar. If you want to change the file name of an image, do so in the media folder. A window will then open suggesting that you automatically update the file name in all instances in the text.

Customizing Images

In AsciiDoc, there are numerous parameters to customize images. The most important ones are:

Parameter Description

width=300 or width=50%

Width in pixels or percent

align=center

Alignment (left, center, right)

alt="Description"

Alternative text for accessibility

An image with parameters looks like this:

image::screenshot.png[alt="Screenshot of the app", width=80%, align=center]
To add an image caption, write a title with a period directly above the image: 
.Figure 1: The user interface
image::screenshot.png[]

The adoc Coach

To keep track of all the parameters, use the adoc Coach.

By clicking the ESC key, the menu opens and shows you all parameters possible at the current text position. If you click ESC between the brackets of an image, you’ll see all available parameters for image design.

media folder

Optimizing Image Resolution

An important topic when exporting is file sizes. Often the product team delivers images in maximum resolution – which is fundamentally good. But a reader on their iPhone doesn’t need images with hundreds of megabytes.

With special attributes, you control the resolution of your images in the output:

Attribute Effect

:ads-max-image-resolution:

Maximum output resolution (in dpi, dpcm, or dppx) when height or width are defined in the source code

:ads-max-image-width:

Limits image width in HTML output when no fixed height or width is specified

:ads-rasterizing-resolution:

PDF, SVG images, and STEM formulas are converted to PNG and set to the specified resolution

:ads-static-stem:

STEM formulas are embedded as SVG instead of rendered with JavaScript

Example for a document with optimized file size:

= My Manual
:ads-max-image-resolution: 150dpi
:ads-rasterizing-resolution: 72dpi
For web documents, 72–150 dpi is often sufficient. For print output, 300 dpi is recommended.
In addition to images, you can also embed audio and video files. The syntax is similar: audio::file.mp3[] and video::file.mp4[]. More information can be found in the Manual.