Include Images

When visualizing complex problems use images to help explain and provide greater information. We use two directories for images.

The image folder structure mirrors the text structure. This makes it easier to locate the AsciiDoc text file where the image is included.

Example folder structure for image files

.
└── 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)

1	This folder contains all documentation modules.
2	The module for this documentation for target group of documentation contributors.
3	Indicates a source folder.
4	The documentation root folder.
5	Folder for images. Images should be .png or .jpg if included in the documentation.
6	The image used; the format is a leading `<number>_` followed by a name using no spaces.
7	Some images are created from tools like yED. This folder should contain the editable version of the file with the same file name.
8	Editable version of the image source file. Note no spaces in the name.
9	Main document file which includes all documentation parts and is rendered as `index.html` for the web.
10	AsciiDoc source file which can include images.
11	Target folder with generated HTML output after `mvn clean package` has been performed.

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 in. Then use the following syntax for inclusion in the document:

First included image

.This is a caption of the image
image::docs/02_opennms-logo.png[]

Which is rendered as:

Figure 1. This is a caption of the image

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