Rendering markdown with pander
Roman Tsegelskyi, Gergely Daróczi
2026-02-04
Source:vignettes/pander.Rmd
pander.RmdPander is designed to provide a minimal and easy tool
for rendering R objects into Pandoc’s markdown. This vignette aims to
introduce the pander package and its core pieces of
functionality. It is intended to be a general overview with pointers to
places with detailed information. This vignette will talk about:
- core functionality for rendering objects in
Pandoc’s markdown with generic S3 pander method. - functionality for capturing various information when evaluating R expressions with evals.
- report generation with Pandoc.brew.
- globally adjustable options through panderOptions/evalsOptions.
Rendering R objects
The core functionality of pander is centered around
rendering R objects into Pandoc’s markdown.
Let’s dive in to a demo of the most common usage of
pander:
pander(head(iris))
#>
#> -------------------------------------------------------------------
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> -------------- ------------- -------------- ------------- ---------
#> 5.1 3.5 1.4 0.2 setosa
#>
#> 4.9 3 1.4 0.2 setosa
#>
#> 4.7 3.2 1.3 0.2 setosa
#>
#> 4.6 3.1 1.5 0.2 setosa
#>
#> 5 3.6 1.4 0.2 setosa
#>
#> 5.4 3.9 1.7 0.4 setosa
#> -------------------------------------------------------------------
pander(head(mtcars[1:5]))
#>
#> --------------------------------------------------------
#> mpg cyl disp hp drat
#> ----------------------- ------ ----- ------ ----- ------
#> Mazda RX4 21 6 160 110 3.9
#>
#> Mazda RX4 Wag 21 6 160 110 3.9
#>
#> Datsun 710 22.8 4 108 93 3.85
#>
#> Hornet 4 Drive 21.4 6 258 110 3.08
#>
#> Hornet Sportabout 18.7 8 360 175 3.15
#>
#> Valiant 18.1 6 225 105 2.76
#> --------------------------------------------------------
pander(tabular( (Species + 1) ~ (n=1) + Format(digits=2)*
(Sepal.Length + Sepal.Width)*(mean + sd), data=iris ))
#>
#> -----------------------------------------------------------------
#> Sepal.Length Sepal.Width
#> Species n mean sd mean sd
#> ------------ ----- ---------------- ------ --------------- ------
#> setosa 50 5.01 0.35 3.43 0.38
#>
#> versicolor 50 5.94 0.52 2.77 0.31
#>
#> virginica 50 6.59 0.64 2.97 0.32
#>
#> All 150 5.84 0.83 3.06 0.44
#> -----------------------------------------------------------------As you have probably guessed, this is achieved via the generic
pander S3 method. Out of the box,
pander supports a variety of classes:
methods(pander)
#> [1] pander.anova* pander.aov* pander.aovlist*
#> [4] pander.Arima* pander.call* pander.cast_df*
#> [7] pander.character* pander.clogit* pander.coxph*
#> [10] pander.cph* pander.CrossTable* pander.data.frame*
#> [13] pander.data.table* pander.Date* pander.default*
#> [16] pander.density* pander.describe* pander.ets*
#> [19] pander.evals* pander.factor* pander.formula*
#> [22] pander.ftable* pander.function* pander.glm*
#> [25] pander.Glm* pander.gtable* pander.htest*
#> [28] pander.image* pander.irts* pander.list*
#> [31] pander.lm* pander.lme* pander.logical*
#> [34] pander.lrm* pander.manova* pander.matrix*
#> [37] pander.microbenchmark* pander.name* pander.nls*
#> [40] pander.NULL* pander.numeric* pander.ols*
#> [43] pander.orm* pander.polr* pander.POSIXct*
#> [46] pander.POSIXlt* pander.prcomp* pander.randomForest*
#> [49] pander.rapport* pander.rlm* pander.sessionInfo*
#> [52] pander.smooth.spline* pander.stat.table* pander.summary.aov*
#> [55] pander.summary.aovlist* pander.summary.glm* pander.summary.lm*
#> [58] pander.summary.lme* pander.summary.manova* pander.summary.nls*
#> [61] pander.summary.polr* pander.summary.prcomp* pander.summary.rms*
#> [64] pander.summary.survreg* pander.summary.table* pander.survdiff*
#> [67] pander.survfit* pander.survreg* pander.table*
#> [70] pander.tabular* pander.ts* pander.zoo*
#> see '?methods' for accessing help and source codeIf you think that pander lacks support for any other R class(es), please feel free to open a ticket suggesting a new feature or submit pull request and we will be happy to extend the package.
Under the hood, pander S3 methods rely on different
pandoc.* methods, where most of functionality is
implemented in pandoc.table which is used for rendering
tables. pandoc.table provides functionality similar to
knitr::kable in rendering markdown, but also adds a truly
rich functionality with a variety of rendering options inherited from
pander. For more usage/implementation details and examples,
please refer to the pandoc.table vignette, which can be
accessed by vignette('pandoc_table') (and is also available
online).
Evals
The pander package was originally developed in
conjunction with rapport package, when a
need arose for a function that could evaluate R expressions
while also capturing errors and warnings. So evals emerged
and soon some further feature requests arose, like identifying if an R
expression results in a plot, etc.
But probably it’s easier to explain what evals can do
with a simple example:
evals('1:10')
#> [[1]]
#> $src
#> [1] "1:10"
#>
#> $result
#> [1] 1 2 3 4 5 6 7 8 9 10
#>
#> $output
#> [1] " [1] 1 2 3 4 5 6 7 8 9 10"
#>
#> $type
#> [1] "integer"
#>
#> $msg
#> $msg$messages
#> NULL
#>
#> $msg$warnings
#> NULL
#>
#> $msg$errors
#> NULL
#>
#>
#> $stdout
#> NULL
#>
#> attr(,"class")
#> [1] "evals"evals is aimed at collecting as much information as
possible while evaluating R code. It can evaluate a character vector of
R expressions, and it returns a list of information captured while
running them:
-
srcholds the R expression, -
resultcontains the raw R object as-is, -
outputrepresents how the R object is printed to the standard output, -
typeis the class of the returned R object, -
msgis a list of possible messages captured while evaluating the R expression. Among other messages, warnings/errors will appear here. -
stdoutcontains what, if anything, was written to the standard output.
For more usage/implementation details and examples, please refer to
the evals vignette, which can be accessed by
vignette('evals') (also available online).
Brew to Pandoc
The brew package, a templating framework for report generation, has not been updated since 2011, but it’s still some of R projects based on its simple design and useful literate programming features. For a quick overview, please see the following documents if you are not familiar with brew:
A brew document is a simple text file with some special tags.
Pandoc.brew uses only two of them (as building on a
personalized version of Jeff’s really great brew function):
-
<% ... %>stands for running inline R commands as usual, -
<%= ... %>does pretty much the same but applies pander to the returning R object (instead ofcatlike the original brew function does). So inserting any R object into the tag would return it in Pandoc markdown format, with all possible error/warning messages, etc.
The latter tries to be smart in some ways:
- A code chunk block (
Rcommands between the tags) can return any number of values at any part of the block. - Plots and images are grabbed in the document, rendered to a png file and pander method would result in a Pandoc markdown formatted image link. This means that the image would be rendered/shown/included in the exported document.
- All warnings/messages and errors are recorded in the blocks and returned in the document as footnotes or inline messages.
- All heavy
Rcommands (e.g. those taking more then 0.1 sec to evaluate) are cached so rebrewing a report would not result in a coffee break.
Besides this, the custom brew function can do more and also less compared to the original brew package. First of all, the internal caching mechanism of brew has been rewritten for benefits besides improved caching. Quick example:
str(Pandoc.brew(text ='Pi equals to `<%= pi %>`. And here are some random data: `<%= runif(10)%>`'))
#> Pi equals to `_3.142_`. And here are some random data: `_0.08075_, _0.8343_, _0.6008_, _0.1572_, _0.007399_, _0.4664_, _0.4978_, _0.2898_, _0.7329_ and _0.7725_`
#> List of 1
#> $ :List of 4
#> ..$ type : chr "text"
#> ..$ text :List of 2
#> .. ..$ raw : chr "Pi equals to `<%=pi%>`. And here are some random data: `<%=runif(10)%>`\n"
#> .. ..$ eval: chr "Pi equals to `_3.142_`. And here are some random data: `_0.08075_, _0.8343_, _0.6008_, _0.1572_, _0.007399_, _0"| __truncated__
#> ..$ chunks:List of 2
#> .. ..$ raw : chr [1:2] "<%=pi%>" "<%=runif(10)%>"
#> .. ..$ eval: chr [1:2] "_3.142_" "_0.08075_, _0.8343_, _0.6008_, _0.1572_, _0.007399_, _0.4664_, _0.4978_, _0.2898_, _0.7329_ and _0.7725_"
#> ..$ msg :List of 3
#> .. ..$ messages: NULL
#> .. ..$ warnings: NULL
#> .. ..$ errors : NULLThe package bundles some examples for Pandoc.brew to let
you quickly check its features. To brew these examples on your machine,
run the following commands:
Pandoc.brew(system.file('examples/minimal.brew', package='pander'))
Pandoc.brew(system.file('examples/minimal.brew', package='pander'),
output = tempfile(), convert = 'html')
Pandoc.brew(system.file('examples/short-code-long-report.brew', package='pander'))
Pandoc.brew(system.file('examples/short-code-long-report.brew', package='pander'),
output = tempfile(), convert = 'html')
Pandoc.brew(system.file('examples/graphs.brew', package='pander'))
Pandoc.brew(system.file('examples/graphs.brew', package='pander'),
output = tempfile(), convert = 'html')General Options
The package comes with a variety of globally adjustable options that
have an effect on the result of your reports. A full list of options can
be viewed by calling ?panderOptions or in the online readme.
You can query and update these options with the
panderOptions function:
pots <- panderOptions("table.style")
panderOptions("table.style", "simple")
pander(mtcars[1:3, 1:4])
#>
#>
#> mpg cyl disp hp
#> ------------------- ------ ----- ------ -----
#> Mazda RX4 21 6 160 110
#> Mazda RX4 Wag 21 6 160 110
#> Datsun 710 22.8 4 108 93
pander(head(iris))
#>
#>
#> Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> -------------- ------------- -------------- ------------- ---------
#> 5.1 3.5 1.4 0.2 setosa
#> 4.9 3 1.4 0.2 setosa
#> 4.7 3.2 1.3 0.2 setosa
#> 4.6 3.1 1.5 0.2 setosa
#> 5 3.6 1.4 0.2 setosa
#> 5.4 3.9 1.7 0.4 setosa
panderOptions("table.style", "grid")
pander(head(iris))
#>
#>
#> +--------------+-------------+--------------+-------------+---------+
#> | Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species |
#> +==============+=============+==============+=============+=========+
#> | 5.1 | 3.5 | 1.4 | 0.2 | setosa |
#> +--------------+-------------+--------------+-------------+---------+
#> | 4.9 | 3 | 1.4 | 0.2 | setosa |
#> +--------------+-------------+--------------+-------------+---------+
#> | 4.7 | 3.2 | 1.3 | 0.2 | setosa |
#> +--------------+-------------+--------------+-------------+---------+
#> | 4.6 | 3.1 | 1.5 | 0.2 | setosa |
#> +--------------+-------------+--------------+-------------+---------+
#> | 5 | 3.6 | 1.4 | 0.2 | setosa |
#> +--------------+-------------+--------------+-------------+---------+
#> | 5.4 | 3.9 | 1.7 | 0.4 | setosa |
#> +--------------+-------------+--------------+-------------+---------+
panderOptions("table.style", pots)