Figures

Options for Creating Figures

Native Markdown

Markdown already supports a simple way of embedding an image in the document:

![Image Alt Text](source-of-the-image.com/img.png)

The command starts with an exclamation mark to indicate that an image is referenced. In square brackets, an alternative title is specified. It is shown in case that the image could not be loaded (and might be used by some screen-readers for visually impaired). The round brackets contain the full URL to the image.

Auto-Relative Paths

A drawback of the native Markdown method is that the absolute URL of the image needs to be specified. If the book is transferred to another URL, all image links will be broken. Therefore, a tool was created which automatically generated the URLs based on the deployment. At the top of the page, the usage of the tool needs to be declared:

{% include autoRelativePath.html %}

After that, images can be specified starting at the root of the book's folder structure. Simply write {{pathToRoot}} and append the folder path to the image from the base folder where the book's editing environment is saved on your disk.

Example:

![Image Alt Text]({{pathToRoot}}/assets/figures/exampleImage.png)

Further information on auto-relative path can be found here

Figure with Caption

Another premade tool allows authors to create figures with captions. The following steps can be performed to create the figure:

1. Include the autoRelativePath at the top of the chapter: {% include autoRelativePath.html %}
2. Include the following figure snippet and change the values accordingly: {% include image.html url="/assets/figures/relativePathToFigure.png" base=pathToRoot description="Caption of the figure" %}
   • Specify the relative URL starting at the base folder of the book to the url field.
   • Specify the caption in the description field.
   • Do not change the base field. It should always state pathToRoot.

HTML Code

Markdown also allows authors to insert HTML snippets. Hence, the following code also works:

<img src="source-of-the-image.com/img.png" alt="Image Alt Text" />

Additionally, text captions can be added to the image this way. In fact, the tool which provides a figure with caption was created this way:

<figure class="image">
    <img src="source-of-the-image.com/img.png" alt="Image Alt Text">
    <figcaption>The caption of the figure</figcaption>
</figure>

Usage Recommendations

It is recommended to use auto-relativePaths for figures without a caption and otherwise use the Figure with Caption tool.