Skip to contents

munch

R-CMD-check

‘munch’ crunches markdown text and ‘flextable’ paragraphs into grid graphics.

‘munch’ started as internal code in ‘flextable’ for rendering rich text with ‘grid’. It was extracted into its own package to also serve ‘ggiraph’ and to provide unified formatting between ‘ggplot2’ graphics and ‘flextable’ tables.

‘munch’ lets you produce this annotated graphic:

The title, subtitle, caption and axis labels above are all built with element_chunks() and ‘flextable’ paragraph objects, bold, italic, colors, highlights, superscripts, subscripts, strikethrough and an embedded image.

Function Purpose Input
element_md() Markdown in theme elements Character string
element_chunks() Advanced formatting in theme elements as_paragraph() object
geom_text_md() Markdown text annotations label aesthetic
geom_label_md() Markdown labels with background label aesthetic

Installation 

# install.packages("pak")
pak::pak("ardata-fr/munch")

Supported graphics devices

‘munch’ requires graphics devices that support ‘systemfonts’: ‘ragg’, ‘svglite’, or ‘ggiraph’. ‘cairo’ devices is also supported when fonts are installed at the system level. See vignette("font-recipes") for font configuration, alternative devices, and troubleshooting.

Quick start

ggplot2

Use element_md() for markdown in theme elements, and geom_text_md() or geom_label_md() for annotations:

library(ggplot2)

ggplot(mtcars, aes(mpg, wt)) +
 geom_point() +
 labs(title = "**Fuel consumption** vs *Weight*") +
 theme(plot.title = element_md(size = 16))

For advanced formatting (superscripts, subscripts, colors), use element_chunks() with ‘flextable’ paragraph objects:

title_chunks <- as_paragraph(
 as_chunk("Model: R"), as_sup("2"), as_chunk(" = 0.75")
)

ggplot(mtcars, aes(mpg, wt)) +
 geom_point() +
 theme(plot.title = element_chunks(title_chunks))

Syntax comparison

Syntax element_md() element_chunks()
Bold / Italic **text** / *text* as_b() / as_i()
Inline code `code` x
Strikethrough ~~text~~ as_strike()
Superscript x as_sup()
Subscript x as_sub()
Custom colors x colorize()
Highlighting x as_highlight()

flextable

Use as_paragraph_md() for markdown in table cells:

ft <- flextable(head(iris, 3))
ft <- mk_par(ft, j = 1, part = "header",
 value = as_paragraph_md("*Sepal* **Length**"))
autofit(ft)

Markdown to grob 

library(munch)
library(grid)

gr <- md_grob("This is **bold** and *italic* text.")
grid.newpage()
grid.draw(gr)

For superscripts, subscripts, or colors not available in markdown, use ‘flextable’ chunks with chunks_grob():

library(flextable)

chunks <- as_paragraph(as_chunk("E = mc"), as_sup("2"))
gr <- chunks_grob(chunks)
grid.newpage()
grid.draw(gr)

Learn more

Comparisons

‘gridtext’

‘gridtext’ by Claus O. Wilke (used by ‘ggtext’) renders formatted text via a subset of HTML/CSS. ‘munch’ takes a different approach: it uses markdown or ‘flextable’ chunks as input and relies on ‘systemfonts’ for text measurement.

munch gridtext
Input format Markdown, flextable chunks HTML / CSS subset
Superscript / subscript Yes (as_sup(), as_sub()) Yes (<sup>, <sub>)
Custom colors / highlight Yes (via colorize(), as_highlight()) Yes (via inline CSS)
Inline images Yes Yes
Text wrapping Yes Yes (textbox_grob())
Text measurement TBD TBD
Integration with ‘flextable’ Yes (shared chunk model) No
Supported devices ‘ragg’, ‘svglite’, ‘ggiraph’, cairo Most R graphic devices
Compiled code No (pure R) Yes (C++ via ‘Rcpp’)

with ‘marquee’

‘marquee’ by Thomas Lin Pedersen offers more markdown features (headings, lists, code blocks, custom spans). ‘munch’ focuses first on integration with ‘flextable’ chunks and advanced formatting not available in markdown.

  • ‘munch’ works with ‘ragg’, ‘svglite’, ‘ggiraph’, cairo_pdf(), png(type = "cairo"), eventually pdf() with few cautions.
  • ‘marquee’ works on a wide range of R devices but not yet with ‘svglite’ or ‘ggiraph’.
  • If working with markdown, ‘munch’ expect only a single paragraph, ‘marquee’ can handle many markdown blocks in one call.