Include images
When visualizing complex problems you can help the explanation and provide greater information by using an image. We use in OpenNMS documentation modules two directories for images.
The image folder structure mirrors the text structure. In this case it is a little bit easier to locate the AsciiDoc text file where the image is included.
.
└── opennms-doc(1)
└── guide-doc(2)
├── README.adoc
├── pom.xml
├── src(3)
| └── asciidoc(4)
| ├── configs
| | └── poller-configuration.xml
| ├── images(5)
| | ├── 01_opennms-logo.png(6)
| | └── 02_pris-overview.png
| ├── images_src(7)
| | └── pris-overview.graphml(8)
| ├── index.adoc(9)
| └── text
| ├── images.adoc(10)
| ├── include-source.adoc
| ├── introduction.adoc
| └── writing.adoc
└── target(11)
-
This folder contains all documentation modules;
-
The module for this documentation for target group of documentation contributors;
-
Indicates a source folder;
-
The documentation root folder;
-
Folder for images. Images should be *.png or *.jpg if included in the documentation;
-
The image used, the format is a leading
<number>_
followed by a name using no spaces; -
Some images are created from tools like yED, this folder should contain the editable version of the file with the same file name;
-
Editable version of the image source file, note no spaces in the name;
-
Main document file which includes all documentation parts and is rendered as
index.html
for the web; -
AsciiDoc source file which can include images;
-
Target folder with generated HTML output after
mvn clean package
has been performed;
Important
|
All images in the entire manual share the same namespace, it is therefore best practice to use unique identifiers for images. |
To include an image file, make sure that it resides in the 'images/' directory relative to the document you’re including it within. Then use the following syntax for inclusion in the document:
.This is a caption of the image
image::../images/01_opennms-logo.png[]
Which is rendered as:

.This is a caption of the image
image::../images/02_example.png[]
Which is rendered as:

Important
|
The image path for the images you include is relative to the *.adoc source file, where you use the image. |