Images
Create high-resolution color screenshots and other static images in .png or .jpg format, with tight cropping on a high-resolution Retina monitor, typically at 144 ppi. Save items into the images
subfolder by chapter. Make sure that color images include high contrast and/or shading, because they will be converted to 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.
If a screenshot requires additional artwork or text for the HTML edition, make a copy of the original and add -ann
to note that this version is annotated, save into the same folder with the same root file name, and use in the code-chunk image pathnames. The publisher will use the original image and add their own artwork for their editions.
If an image is larger than approximately 300px on either side, one more option is to reduce the image size in the PDF version. Use Photoshop (not Preview) to reduce the image size, and save a copy with the same file name with the .pdf extension into the folder. In some cases, the folder will contain only one version of each image, but in other cases it may contain up to three versions of an image:
images/05-chart/design-no-junk.png
images/05-chart/design-no-junk-ann.png
images/05-chart/design-no-junk-ann.pdf
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.
Images using R code-chunks
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. Note that Word formatting can be changed with reference.docx.
Write R code-chunk labels that follow the image file name, and avoid duplicate labels across the book:
ref:design-no-junk
images/05-chart/design-no-junk.png
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.
For each figure, manually add a cross-reference call-out and insert fig.pos='h'
to place the image “here” on the page in the PDF output, to attempt to avoid PDF floating. Ignore the Bookdown LaTeX warning message “h float specifier changed to ht.” See more at https://bookdown.org/yihui/bookdown/figures.html and https://bookdown.org/yihui/rmarkdown-cookbook/figure-placement.html
This Bookdown index.Rmd
file includes two global R code-chunk settings immediately after the first header. One setting displays each code-chunk image without a code echo. The other setting automatically inserts the PDF version of an PNG/JPG image, whenever it exists, in the PDF output, which allows us to manually reduce the image sizes for the PDF book. Read more about these options in this Bookdown chapter: https://bookdown.org/yihui/bookdown/figures.html.
{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)
options(knitr.graphics.auto_pdf = TRUE)
Demo: R code-chunk for small static image
Small is defined as each side less than 300px, as shown in Figure 1.1.
![Caption here. Markdown embedded links are acceptable.](images/tiger.png)
Figure 1.1: Caption here. Markdown embedded links are acceptable.
R code-chunk for larger static image using out.width and PDF img
For larger images, where one side is greater than 300px, set the out.width to a pixel number for ideal display in the HTML edition. Also, if needed, copy the image, use Photoshop to create a smaller image size, and save with same file name and a .pdf extension for auto-substitution in the PDF output …as shown in Figure 1.2.
![Using out.width=200 and smaller PDF image size.](images/screenshot-tall.png)
Figure 1.2: Using out.width=200 and smaller PDF image size.
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. To change the height of the default 400px iframe, add the new height to include_url
as shown in the examples. However, to change the width of the default 675px iframe to less than 100 percent, add a line in a custom-scripts.html
file.
Demo: R code-chunk for HTML iframe and static image for PDF & Markdown
…as shown in Figure 1.3.
Figure 1.3: Caption here, and add embedded link to explore the full-screen interactive map
Demo: R code-chunk for GIF animation in HTML and static image in PDF and Markdown
…as shown in Figure 1.4.
Figure 1.4: Caption here, with embedded link to animated GIF.
Demo: R code-chunk for Youtube video in HTML and static image in PDF and Markdown
Be sure to use the embed link from the YouTube share button.
…as shown in the video 1.5.
Figure 1.5: Caption here, with embedded link to the YouTube video.
Demo: R code-chunk for YouTube video in HTML, with NO static image in PDF
Figure 1.6: Caption only for HTML version, with embedded link to the YouTube video. How will this affect figure numbering in HTML vs PDF?