12.5 Output figures in the HTML5 format

By default, plots in R Markdown are included in the tag <img src="..." /> in a <p> or <div> tag in the HTML output. This example below shows how to use the HTML5 <figure> tag to display plots.

  1. ---
  2. title: Output figures in `<figure>` tags
  3. output: html_document
  4. ---
  6. Given a plot file path `x` and a figure caption in the chunk
  7. option `options$fig.cap`, we want to write the plot in the
  8. HTML5 tag in this form:
  10. ```html
  11. <figure>
  12.   <img src="PATH" alt="CAPTION" />
  13.   <figcaption>CAPTION</figcaption>
  14. </figure>
  15. ```
  17. Now we redefine the `plot` hook (only when the output format
  18. is HTML):
  20. ```{r}
  21. if (knitr::is_html_output()) knitr::knit_hooks$set(
  22.   plot = function(x, options) {
  23.     cap  <- options$fig.cap  # figure caption
  24.     tags <- htmltools::tags
  25.     as.character(tags$figure(
  26.       tags$img(src = x, alt = cap),
  27.       tags$figcaption(cap)
  28.     ))
  29.   }
  30. )
  31. ```
  33. The plot from the code chunk below will be placed in the
  34. `<figure>` tag:
  36. ```{r, fig.cap='A scatterplot for the cars data.'}
  37. par(mar = c(4.5, 4.5, .2, .2))
  38. plot(cars, pch = 19, col = 'red')
  39. ```
  41. We add some CSS styles to "see" the `<figure>` and
  42. `<figcaption>` tags better (the `figure` has a dashed
  43. border, and the caption has a light pink background):
  45. ```{css, echo=FALSE}
  46. figure {
  47.   border: 2px dashed red;
  48.   margin: 1em 0;
  49. }
  50. figcaption {
  51.   padding: .5em;
  52.   background: lightpink;
  53.   font-size: 1.3em;
  54.   font-variant: small-caps;
  55. }
  56. ```

The figure output is shown in Figure 12.2. Note that we actually overrode the default plot hook in this example, while most other examples in this chapter build custom hooks on top of the default hooks. You should completely override default hooks only when you are sure you want to ignore some built-in features of the default hooks. For example, the plot hook function in this case did not consider possible chunk options like out.width = '100%' or fig.show = 'animate'.

A figure in the HTML5 figure tag.

FIGURE 12.2: A figure in the HTML5 figure tag.

This example shows you what you can possibly do with the plot file path x in the plot hook. If all you need is to customize the style of figures, you do not have to use the HTML5 tags. Usually the default plot hook will output images in the HTML code like this:

  1. <div class="figure">
  2.   <img src="PATH" />
  3.   <p class="caption">CAPTION</p>
  4. </div>

So you can just define css rules for div.figure and p.caption.