Create high-resolution color static images in .jpg or .png format, and animated .gif files, and save them into the images subfolder by chapter. Make sure that color images can be rendered into grayscale by the publisher for the print book. Write file names in lowercase with dashes (not spaces) and begin with keyword of relevant section to keep related images grouped together. Despite being in separate folders, avoid duplicate image file names across the book. Avoid numbering images since they may not match the final sequence. Add -original to the end of the file name prior to resizing or adding more text or artwork.

Use Photoshop or a similar photo-editing tool (not Preview) to add any additional text or artwork if desired. Try to maintain a high resolution (300 dpi) and reduce size if desired to fit into the HTML book (measured in pixels) and PDF book (measured in inches). Save into the same folder with the same file name, minus -original, like this:


When inserting image filenames into the text, use the version minus -original. If creating images to appear as the same size in sequence, add a code-comment with the image width, height, and resolution as a reminder to make others match up, like this:

<!-- Images below are 200x200 at 300 resolution -->

In this book, use Markdown formatting only for images that appear inside tables or do not require captions or figure numbering, and leave the caption field blank, like this example:

Co-Authors About Us
About Jack Dougherty
About Ilya Ilyankou

Although Markdown formatting offers a simple syntax that easily converts into other formats with Bookdown/Pandoc, there is no auto-numbering in the HTML edition, while auto-numbering appears in the PDF edition, and numbered figures are required by the publisher. Furthermore, Markdown formatting does not allow conditional output.

For these reasons, this book primarily uses R code-chunk formatting for images. The syntax is more complex but supports auto-numbering in HTML and PDF, and conditional output for interactive and static images. Note that R code-chunk images do not easily convert with Pandoc from Markdown to AsciiDoc, but “Figure x Caption” appears as a placeholder.

Auto-numbering appears in Figure x.x format in HTML and PDF, but Figure x format in MS Word. TODO: Check if Word formatting can be changed with reference.docx.

Note that images in PDF output will “float” by design and may appear before or after the desired page, so always add a cross-reference call-out.

Write R code-chunk labels that follow the image file name, and avoid duplicate labels across the book:



Do not insert spaces inside the ref:chunk-label for the caption, but add a blank line to separate it from the code-chunk. After the code-chunk, add another blank line.

Demo: R code-chunk for static image

…as shown in Figure 15.1.

Caption here. Markdown embedded links are acceptable.

Figure 15.1: Caption here. Markdown embedded links are acceptable.

R code-chunks allow more complex conditional formatting, where an interactive map or animated GIF or YouTube video clip appears in the web version, and a static image with an embedded link appears in the PDF and MS Word outputs. Also note the option to change the default iframe height (400px) and width with settings in the custom-scripts.html file, with a code comment reminder.

Demo: R code-chunk for HTML iframe and static image

…as shown in Figure 15.2.

Figure 15.2: Caption here, and add embedded link to explore the full-screen interactive map.

Demo: R code-chunk for GIF animation and static image

TODO: FIX to make sizing appear consistently across browsers (FFox vs Chrome).

…as shown in Figure 15.3.

Figure 15.3: Caption here, with embedded link to GitHub repo, not GitHub Pages animated GIF.

Demo: R code-chunk for Youtube video and static image

Be sure to use the embed link from the YouTube share button.

…as shown in the video 15.4.

Figure 15.4: Caption here, with embedded link to the YouTube video.

This Bookdown index.Rmd file includes an R code-chunk setting immediately after the first header, which displays each code-chunk image without a code echo. Read more about this feature and related options in this Bookdown chapter.

{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)