This vignette covers formatting in ‘ggplot2’ theme elements and text
annotations using ‘munch’.
Simple markdown with element_md()
element_md() replaces element_text() to
render markdown in titles, subtitles, captions, and axis labels.
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
labs(
title = "**Fuel Consumption** vs *Weight*",
subtitle = "Data from the `mtcars` dataset",
caption = "Source: *Motor Trend* (1974)"
) +
theme(
plot.title = element_md(size = 16),
plot.subtitle = element_md(size = 12),
plot.caption = element_md(size = 9)
)
ggplot(mtcars, aes(hp, mpg)) +
geom_point() +
labs(
x = "Horsepower (*hp*)",
y = "Miles per gallon (**mpg**)"
) +
theme(
axis.title.x = element_md(),
axis.title.y = element_md()
)
For advanced markdown rendering (images, spans, custom CSS), see also
marquee::element_marquee().
Text annotations with geom_text_md() and geom_label_md()
geom_text_md() and geom_label_md() render
markdown-formatted labels directly on the plot, similar to
geom_text() and geom_label().
annotations <- data.frame(
x = c(15, 25, 30),
y = c(4, 3, 2),
label = c("**Group A**", "*Group B*", "`Group C`")
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point(alpha = 0.5) +
geom_text_md(
data = annotations,
aes(x = x, y = y, label = label),
size = 4
)
geom_label_md() adds a background rectangle for better
readability:
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
geom_smooth(method = "lm", se = FALSE) +
geom_label_md(
label = "**R\u00B2 = 0.75**\n\n*p < 0.001*",
x = 28, y = 5,
hjust = 0, vjust = 1,
fill = "white",
label.padding = unit(0.5, "lines")
)
Text wrapping
geom_text_md() and geom_label_md() support
the width parameter (in inches) for automatic line
wrapping:
df <- data.frame(
x = c(15, 30),
y = c(4, 2.5),
label = c(
"This is a **long annotation** that will be *wrapped* automatically when it exceeds the specified `width`.",
"A shorter **note**."
)
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point(alpha = 0.3) +
geom_text_md(
data = df,
aes(x = x, y = y, label = label),
width = 2, hjust = 0, size = 3.5
)
Images in labels
Use markdown image syntax  to embed images in
geom_label_md():
r_logo <- file.path(R.home("doc"), "html", "logo.jpg")
df <- data.frame(
x = 20, y = 4,
label = sprintf("Built with  and **ggplot2**", r_logo)
)
ggplot(mtcars, aes(mpg, wt)) +
geom_point() +
geom_label_md(
data = df,
aes(x = x, y = y, label = label),
fill = "white",
label.padding = unit(0.5, "lines")
)
Alignment accuracy
‘munch’ splits text into individually-styled chunks and measures each
chunk width separately using ‘gdtools’. The widths are then summed to
obtain the total line width. This approach works well in most cases, but
it does not produce the same result as a full text shaping engine such
as textshaping or systemfonts. Those engines compute the width of a
complete string and account for kerning pairs, ligatures, and glyph
substitutions between adjacent characters, adjustments that are lost
when characters belong to separate chunks. The summed width is close but
not exact.
The practical effect depends on the horizontal justification:
hjust = 0 (left-aligned): unaffected. The left edge is
always anchored at x = 0, so any width discrepancy has no visible
impact.hjust = 0.5 (centered): minor. The measurement error is
split equally on both sides.hjust = 1 (right-aligned): most visible. The right edge
of successive wrapped lines may not align precisely because each line
carries a slightly different measurement error.
For best accuracy, prefer left or center alignment. Right alignment
may show slight edge misalignment on multi-line text.
This is a known limitation and work is in progress to reduce the
gap.
