The ggtext package provides simple Markdown and HTML rendering for ggplot2. Under the hood, the package uses the gridtext package for the actual rendering, and consequently it is limited to the feature set provided by gridtext.

Support is provided for Markdown both in theme elements (plot titles, subtitles, captions, axis labels, legends, etc.) and in geoms (similar to geom_text()). In both cases, there are two alternatives, one for creating simple text labels and one for creating text boxes with word wrapping.

Importantly, the gridtext package that provides the rendering support implements only an extremely limited subset of Markdown/HTML/CSS. It currently can make text bold or italics, can change the font, color, or size of a piece of text, can place text as sub- or superscript, and has extremely rudimentary image support. No other features are currently supported. As a general rule, any Markdown, HTML, or CSS feature that isn’t shown in any of the ggtext or gridtext documentation likely doesn’t exist.

Installation

To install the latest development version of this package, please run the following line in your R console:

remotes::install_github("wilkelab/ggtext")

Once the package is available on CRAN, you will be able to install the latest release via install.packages() as usual:

Markdown in theme elements

The ggtext package defines two new theme elements, element_markdown() and element_textbox(). Both behave similarly to element_text() but render the provided text as markdown/html. element_markdown() is meant as a direct replacement for element_text(), and it renders text without word wrapping. To start a new line, use the <br> tag or add two spaces before the end of a line.

As an example, we can mix regular, italics, and bold text, and we can also apply colors to axis tick labels. This particular example was inspired by this stackoverflow post.

library(tidyverse)
library(ggtext)
library(glue)

data <- tibble(
  bactname = c("Staphylococcaceae", "Moraxella", "Streptococcus", "Acinetobacter"),
  OTUname = c("OTU 1", "OTU 2", "OTU 3", "OTU 4"),
  value = c(-0.5, 0.5, 2, 3)
)

data %>% mutate(
  color = c("#009E73", "#D55E00", "#0072B2", "#000000"),
  name = glue("<i style='color:{color}'>{bactname}</i> ({OTUname})"),
  name = fct_reorder(name, value)
)  %>%
  ggplot(aes(value, name, fill = color)) + 
  geom_col(alpha = 0.5) + 
  scale_fill_identity() +
  labs(caption = "Example posted on **stackoverflow.com**<br>(using made-up data)") +
  theme(
    axis.text.y = element_markdown(),
    plot.caption = element_markdown(lineheight = 1.2)
  )

Very basic support for the <img> tag exists, and it can be used, for example, to employ images as axis labels.

element_textbox() offers support for rendering larger amounts of text that require word wrapping. Unlike element_markdown(), it cannot be used for axis tick labels, and it cannot draw text at arbitrary angles, only at fixed orientations corresponding to 0, 90, 180, and 270 degrees. In practice, you will usually want to use element_textbox_simple() instead of element_textbox(), as it sets useful defaults for many parameters not usually defined in ggplot2 themes.

Another example, replacing facet strips with text boxes.

Geoms

The geom geom_richtext() provides markdown/html labels. Unlike geom_label(), the labels can be rotated.

Labels without frame or background are also possible.

The geom geom_textbox() can draw boxes with word-wrapped text. It does not support arbitrary rotation angles, only fixed orientations, just like element_textbox().

Acknowledgments

This project is receiving financial support from the R consortium.