Contributing - Formatting Vaadin Documentation with AsciiDoc
 Edit This Page

Formatting Vaadin Documentation with AsciiDoc

Marko Grönroos, Vaadin Ltd.

This document briefly describes basic styling of Vaadin AsciiDoc documentation.

The content here is still preliminary. Old but mostly valid instructions are given in the AsciiDoc Reference for Vaadin Documentation (PDF).


Image Basics

Images include screenshots and diagrams. They must always have a caption and an ID, unless inside a step-by-step list. The ID must follow the ID hierarchy of the containing section. It must be prefixed with figure.. Images must always be referenced from text.

The result is shown in <<figure.contributing.formatting.image.example>>.

.An example of an image
image::img/mymodule-example.png[width=70%, scaledwidth=100%]

It would render as:

vaadin logo
Figure 1. An example of an image

Images should be located under img sub-folder.


The caption may not be in title case.

References to images use the caption text in the reference. However, it is used differently in Vaadin Docs and the print edition.

In Vaadin Docs, it is shown as is in the link.

The result is shown in An example of an image.

In print or PDF version, the reference includes "Figure x.x <caption>", with the chapter number and figure number in the chapter.

The result is shown in Figure 1.1, "An example of an image".

Requirements for Illustrations

Illustrations have the following requirements:

Always use white background

Paper is white.
When taking screenshots, use a white background when necessary. Make sure the white background does not get transparent when taking screenshots.

Do not use transparency in images

PNG and GIF images allow transparency. While they may show fine in the website, in PDF the transparent parts are rendered as black. This makes them very ugly.

Use high resolution for screenshots

Otherwise, the pixels will show up ugly when the images are scaled. You can use the browser zoom feature to enlarge Vaadin UIs. Scale the images as described in Image Scaling.

Minimize screenshot content

Space is prescious escpecially in the print edition.
Select only the relevant area for the screenshot. Sometimes, adding some cut context may clarify the screenshot. Some views or dialog windows can be overly complex or large. You should consider simplifying them with an image editor. You can use Photoshop or Gimp or whatever.

Fonts must not be too small

The text column in the print edition is 82 mm (3.23 inches) wide. Height of the normal font is 2 mm or 6 points (1/72"). That means around 1/40th of the text column width. Text in diagrams should not be much smaller than this. If text is less than half of this, it is unreadable.

For example, if an image is 800 pixels wide and scaled as 100%, the normal font should be 20 pixels high. Text would have to be at least 10 pixels high, and anything smaller would anyhow be blurry.

Image Scaling

Images are displayed in at least three formats: Vaadin Docs website, pocket-book sized print edition, and large size PDF. There could also be an additional ePub format. All images need to be scaled for all these resolutions.

AsciiDoc has two scaling parameters: width and scaledwidth.

image::img/mymodule[width=70%, scaledwidth=100%]
width (optional)

This parameter is used for the HTML web edition in Vaadin Docs. The images are automatically limited to the maximum width of the text area.


This parameter is used for the print and PDF editions. It is used as is for the pocket-size edition. For the large PDF edition, it is multiplied by 0.8, as otherwise the images intended for the print edition would get too large.

Taking Screenshots