Adding image files

Our template comes with four folders for images, which correspond to output formats: print-pdf, screen-pdf, web and epub. Save your images files there. Each folder should contain the same set of images, saved appropriately for each format. For instance, while their file names must be identical, web images might be full-colour, 96dpi, and up to 800 pixels wide; while print-pdf images might be in greyscale, 300dpi and 2400 pixels wide.

Automating image conversions

You can automate the conversion of images to various outputs with gulp. You need to have npm installed, and to have run nom install in the project root to install the node_modules.

Then you only need to put high-res versions of your images in images/_source and run gulp. Our gulp script will automatically optimise, convert and save your images to the four output folders, including specifying the correct colour profiles and creating multiple image sizes for web output.

By default, gulp will convert the images in your book folder. To convert the images in a different folder, say my-potato-book:

gulp --book my-potato-book

If you’re processing image files in a translation subdirectory, specify the language by its code. E.g.:

gulp --language fr

Adding images in markdown

We use standard markdown to embed images:

![A description of the image](../{{ site.image-set }}/filename.svg)

Let’s break that down:

Images in translations

If you are creating a translation in a subdirectory of text, and your images are in the parent book folder, you need to change the path to the images slightly. You have two options:

  1. Use the {{ path-to-book-directory }} metadata tag. At the top of your markdown file, add {% include metadata %}, so that you can use metadata variables in that file. Then instead of any ../s, you use the tag: {{ path-to-book-directory }}{{ site.image-set }}/filename.jpg.

    Even if you’re not in a translation folder, it’s good practice to always use the {{ path-to-book-directory }} tag for maximum portability, if you don’t mind having the {% include metadata %} tag at the top of your files.

  2. Add another ../ for each directory level. So if your translation text is in book/text/fr, you need to come up three levels before going into book/images. So your path is ../../{{ site.image-set }}/filename.jpg.


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](../{{ site.image-set }}/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.)

This will display like this.

Line drawing of a book

This is not a book.

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

> ![Figure 2-A: The Ballard scoring method](../{{ site.image-set }}/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](../{{ site.image-set }}/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 blind 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'. Here 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”."

Alternative image sets

There are often good reasons for producing books with different sets of images. For instance, one edition may have colour images and another black-and-white. Or your print edition might call for high-res images, but you want low-res ones for the ebook.

You want Jekyll to get images from the right image set. We do this by using the {{ site.image-set }} tag to refer to whatever format-specific image set Jekyll should use.

For example:

![]({{ site.image-set }}/filename.jpg)

To always use a specific image file for any given image, irrespective of the images-set config, simply hard-code your image path in markdown – that is, without using the {{ site.image-set }} tag. For example, for a given image you might specify the default images folder ![](images/filename.jpg) or a specific subfolder ![](images/nb/filename.jpg).

If you’re using `

to add your figures, you don't need to specify any path or site.image-set`. The figure include does that for you.

Image placement

You may need to control how an image is sized and placed on the page – especially in print – depending on its detail or aspect ratio and nearby images or other elements. You do this by adding a class tag to the line following the image or figure created with a > blockquote. (This applies a class to the blockquote in HTML.)

You have two broad options:

The lazy way: use these class attributes:

You add these classes to the `{:.figure} tag like this:

{:.figure .small}

{:.figure .fixed}

and so on. You can combine size and placement classes like this, too:

{:.figure .fixed .small}

The more accurate way: use a class tag to specify the exact height of the image in lines. This is important if you’re maintaining a baseline grid on your pages. For instance, {:.height-5} will limit the image to a height of five lines. Unlike the lazy way above, this tag should be applied to the image, not the figure. So a complete figure element might look like this in markdown:

> ![Potatoes on the moon](images/web/1-moon-potatoes.jpg)
> {:.height-12}
> Potatoes grow well on the moon if well watered.

CSS tip: If you’re having trouble with SVGs having space around them, in your CSS make sure you set the height of the img element. SVGs are inline elements by default, and will add white space around them.

Preparing images

Using SVG images

If you choose to use SVG:

Here’s our most common workflow for converting images to SVG:

Image sizes

We like to use these settings where possible:

Using Illustrator? Different SVG editors treat image size differently. For instance, a 2-inch-wide image in Illustrator will appear 1.6 inches wide in Prince and Inkscape. Why? Because when creating the SVG’s XML, Illustrator includes its dimensions in pixels, and assumes a 72dpi resolution, where Prince and Inkscape follow the W3C SVG spec and assume 90dpi. As a result, images coming out of Illustrator always appear 80% of their intended size. So, if you’re creating images in Illustrator, set your image sizes to 125% of what you intend to appear in the book. That means:

Check out Adobe’s guidance on saving SVGs.

If your SVG files seem big, read up on optimising SVGs, and/or (if you’re comfortable using Python scripts) run your SVGs through Scour.


Image styles

We like these approaches to artwork, where possible:

If you use live trace to create art from a raster source, you must clean up the file to remove unnecessary fills that add to file size but do little for clarity.

Raster images should follow the sizing constraints above and be saved as jpg (since older Amazon Kindles only use JPG or GIF, avoid PNG or other formats). Save as RGB.

Cover images

Add the front-cover image to the book’s images folder. Ensure colour settings are RGB and the DPI is set to 72. We recommend creating the image in three sizes:

The first is mandatory. The thumbnail and large images are for your convenience. For instance, when uploading a book to Amazon Kindle, you must provide a cover image this large.