library(knitr)
There are a variety of ways to layout figures included within Distill articles. This layout is controlled by a set of layout classes, which are in turn applied to R Markdown chunks using the layout
chunk option.
The default layout if layout
is not specified is l-body
, which will cause content to span the width of the main article body:
::: {.fake-img .l-body}
l-body
:::For example, a plot with the default l-body
layout would look like this:
include_graphics("images/l-body-figure.png")
For elements you want to display a little larger, try l-body-outset
or l-page
:
::: {.fake-img .l-body-outset}
l-body-outset
:::::: {.fake-img .l-page}
l-page
:::For example, here the l-body-outset
layout is selected using the layout
chunk option:
```r`r ''` library(ggplot2) ggplot(diamonds, aes(carat, price)) + geom_smooth() + facet_grid(~ cut) ```
include_graphics("images/l-middle-figure.png")
Note that when specifying an alternate layout
you should also specify an appropriate fig.width
and fig.height
for that layout.
Occasionally you'll want to use the full browser width. For this, use l-screen
:
::: {.fake-img .l-screen}
l-screen
:::If you want a bit space at the edges then you can use the l-screen-inset
layout, which adds 15 pixels of padding to each side. Here we use l-screen-inset
to display a Leaflet map:
```r`r ''` library(leaflet) leaflet() %>% addTiles() %>% # Add default OpenStreetMap map tiles addMarkers(lng=174.768, lat=-36.852, popup="The birthplace of R") ```
library(leaflet) leaflet() %>% addTiles() %>% # Add default OpenStreetMap map tiles addMarkers(lng=174.768, lat=-36.852, popup="The birthplace of R")
Depending on the content displayed by l-screen-inset
, sometimes it's nice to add some shading to further deliniate the display. You can do this by adding shaded
to the layout declaration:
```r`r ''` library(leaflet) leaflet() %>% addTiles() %>% # Add default OpenStreetMap map tiles addMarkers(lng=174.768, lat=-36.852, popup="The birthplace of R") ```
library(leaflet) leaflet() %>% addTiles() %>% # Add default OpenStreetMap map tiles addMarkers(lng=174.768, lat=-36.852, popup="The birthplace of R")
To include static figures (i.e. figures based on an existing PNG or JPEG file rather than a dynamically generated R plot), you can use the knitr::include_graphics()
function:
```r`r ''` knitr::include_graphics("images/figure.png") ```
You can apply Distill layouts to static figures the same way that you do plots:
```r`r ''` knitr::include_graphics("images/figure.png") ```
If you are including a figure from an external source, it's good practice to delineate this by applying the external
class and adding a caption indicating where it is from. For example:
```r`r ''` knitr::include_graphics("images/heatmap.png") ```
Using the external
class and providing a "Figure from" link makes it clear that the figure originated elsewhere (and is therefore not covered by any of your article's copyright or creative commons license grants). For example, here's how a figure taken from a Stack Overflow post might appear:
{.external width="100%"}
When you assign a figure caption to a code chunk via the chunk option fig.cap
, R plots will be put into figure environments, which will be automatically labeled and numbered, and can also be cross-referenced.
For example, here we add a fig.cap
to one of our previous examples:
```r`r ''` library(ggplot2) ggplot(diamonds, aes(carat, price)) + geom_smooth() + facet_grid(~ cut) ```
The label of the figure environment is generated from the label of the code chunk, e.g., if the chunk label is diamonds
, the figure label will be fig:diamonds
(the prefix fig:
is added before diamonds
.
To reference a figure, use the syntax \@ref(label)
, where label is the figure label. So for the example above we'd use \@ref(fig:diamonds)
, which would result in a cross-reference like this:
include_graphics("images/figure-cross-references.png")
For additional documentation on figure cross-references see the bookdown documentation on figures (Distill for R Markdown uses the bookdown implementation of cross-references under the hood).
One important constraint to keep in mind is that if you want to cross-reference figures or tables generated from a code chunk, please make sure the chunk label only contains alphanumeric characters (a-z, A-Z, 0-9), slashes (/), or dashes (-).
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.