A figure is the combination of an image and a caption. Sometimes a figure can include things like tables or video instead of images, and the captions can be accompanied by things like titles and sources.

Simple markdown figures

You can create simple markdown figures that include an image followed by a caption. We put these together in a <blockquote> element with a .figure class. We can then control placement by styling the <blockquote>.

The reason we use a blockquote is that it lets us keep images and their captions together. A <figure> element would be better HTML, but it won’t validate in EPUB2, and can’t be created with kramdown.

Here’s an example of markdown for a figure:

> ![Line drawing of a book](../images/web/book.jpg)
> This is not a book.

Every line (except the {:.figure} class tag at the end) starts with a > and a space. These wrap the figure (image and caption) in a blockquote element.

The first line is the image reference. As noted above, it consists of:

The third line is the figure caption, followed by the kramdown tag {:.figure}, which lets our stylesheets format the blockquote as a figure. (For instance, preventing a page break between the image and the caption in print.)

If your image has no caption, just skip the empty line and caption line:

> ![Figure 2-A: The Ballard scoring method](../images/web/fig-2-A.svg)

If it’s important to you that the image isn’t in a blockquote, and there is no caption, you can use:

![Figure 2-A: The Ballard scoring method](../images/web/fig-2-A.svg)

Advanced figures

Figures are much more powerful if you use the figure include. The figure include is a dedicated piece of code in our template that creates figures with many options.

To include a figure this way, start with this simple tag:

{% include figure %}

Then, inside that tag after the word figure, you add extra info, depending what you need it to include.

In the tag for each figure, we can define the following information:

The template uses that information differently depending on the output format. For instance, on the web and in the epub, the description is the text that screen-readers will read aloud to visually impaired users who can’t see an image; and we don’t need to display it in print.

A caption and a description are similar, but not the same. A caption usually provides information about the figure, while a description describes its appearance.

We define these things in the tag using ‘parameters’. For instance, we set the image parameter by writing image='mydog.jpg'. Below is a figure include with each parameter set. You can copy this and set the value in each parameter. Nothing is mandatory, so you only need to include the parameters that your figure needs defined.

Here is a full example:

{% include figure
   images="mydog.jpg, yourdog.jpg"
   markdown="A *bad* example."
   reference="Figure 1.2a"
   caption="This is the figure caption."
   title="My Example Figure"
   description="This should describe what the images look like."
   source="Fire and Lion, 2017"

Note the double quotes. If the text you’re adding to a parameter contains quotes, you’d use single quotes in the text – or vice versa. Do not mix single and double quotes, or the software won’t know where the parameter ends. If you must use, say, double quotes inside the quotes around a parameter, use the actual unicode glyphs for curly quotes, and . For instance, all of these are okay:

caption="Blake's illustration for 'The Tyger'."
caption='Blake's illustration for "The Tyger".'
caption="Blake's illustration for “The Tyger”."

Rotating figures

If you need to rotate a large figure on the page, add the rotate class. E.g.

{% include figure
   reference="Figure 1.1"
   caption="A really huge table."

Rotation only affects PDF output.

Figure width

If you need to make a figure narrower than the full text area, add a width-x class, where x is the width you want in percent. E.g. width-50 will create a half-width image.