Illustrate concepts with diagrams

Table of Contents

There are a number of ways to create diagrams for use in Distill articles, a few worth considering are:


You can use the DiagrammerR package to include GraphViz visualizations within a Distill article. For example, if you have a GraphViz file graph.gv, you can include it with the following code:

```{r, layout="l-page", fig.height=2}

Note that since this diagram is much wider than it is tall, we specify layout="l-page" to provide adequate horizontal layout space and fig.height=2 to ensure the correct aspect ratio. See the documentation on figure layout for details on all available layout options.

DiagrammeR also supports diagrams created with Mermaid. For example:

mermaid(diagram = '
  participant Alice
  participant Bob
  Alice->>John: Hello John, how are you?
  loop Healthcheck
      John->>John: Fight against hypochondria
  Note right of John: Rational thoughts<br/>prevail...
  John-->>Alice: Great!
  John->>Bob: How about you?
  Bob-->>John: Jolly good!

D3 diagrams

The r2d3 package enables you to include illustrations created using D3.js. For example, the following code renders flare.json using the circlepacking.js script:

```{r, layout="l-screen-inset", fig.height=8}
data <- jsonlite::read_json("flare.json")
r2d3(data, script = "circlepacking.js")

This is an illustration that has lots of detail so it benefits from being rendered at nearly full screen width (layout="l-screen-inset"). We also specify fig.height=8 to cause the illustration (which has a square aspect ratio) to take advantage of the additional horizontal space.

Static diagrams

For more highly customized static diagrams you can use a vector graphics tools like Inkscape, Adobe Illustrator, or Sketch.

These programs are all capable of exporting SVG (Scalable Vector Graphics). Once you’ve exported an SVG you can include it in your article using the knitr::include_graphics() function. For example, to include the SVG file created within this Inkscape tutorial you would use the following code:


This particular illustration uses the default layout (occupying the full width of the article text). Note though that you can use the various figure layout options to control the size and placement of SVG files included from illustration programs.


If you see mistakes or want to suggest changes, please create an issue on the source repository.


Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/rstudio/distill, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".