pander: An R Pandoc Writer

The main aim of the pander R package is to provide a minimal and easy tool for rendering R objects into Pandoc's markdown. The package is also capable of exporting/converting complex Pandoc documents (reports) in various ways. Regarding the difference between pander and other packages for exporting R objects to different file formats, please refer to this section.

Current build and test coverage status: .

Some CRAN statistics:

Installation

The stable version can be installed easily in the R console like any other package:

install.packages('pander')

On the other hand, I welcome everyone to use the most recent version of the package with quick-fixes, new features and probably new bugs. It's currently hosted on GitHub. To get the latest development version from GitHub of the devtools package from CRAN:

devtools::install_github('Rapporter/pander')

Dependencies

Few cool packages from CRAN are needed for installing and/or using pander:

• digest to compute hashes while caching,
• Rcpp to compile certain functions used by the package.

And there are also a few optional suggested or supported R packages, such as:

• sylly to use hyphenation when splitting large table cells,
• lattice and ggplot2 for unified plot theme,
• logger for logging capabilities inside evals,
• survival, microbenchmark, zoo, nlme, descr, MASS, tables, reshape, memisc, Epi, randomForest, tseries, rms packages include some supported R classes,
• and pander can be also very useful inside of knitr. More information about how to use pander and knitr can be found specialized vignette, which can be accessed by vignette('knitr', package = 'pander') or available online here.

Pandoc

pander heavily builds on Pandoc, which should be pre-installed before trying to convert your reports to different formats. Although main functions work without Pandoc, e.g. you can transform R objects into markdown or generate a markdown formatted report via Pandoc.brew or the custom reference class, but installing that great piece of software is suggested if you want to convert markdown to PDF/docx/HTML or other formats.

Starting v0.98.932 RStudio comes with a bundled Pandoc binary, so one can save the tedious steps of installing Pandoc.

If you do not have RStudio installed, please refer to the installation process of Pandoc, which is quite straightforward on most-popular operating systems: download and run the binary (a few megabytes), and get a full-blown document converter in a few seconds/minutes. On some Linux distributions, it might be a bit more complicated (as repositories tend to provide out-dated versions of Pandoc, so you would need cabal-install to install from sources). Please do not forget to restart your R session to update your PATH after installation!

Helper functions

The package contains numerous helper functions, which render user specified inputs in Pandoc's markdown format or apply some extra formatting on it. All Pandoc-related functions' names are starting with pandoc. For example pandoc.table is used for rendering tables in markdown. For a technical documentation, see the HTML help files of the package at Rdocumentation.

<a id="primitive-functions"></a>

All pandoc functions generally prints to console and do not return anything by default. If you want the opposite, to get markdown in a string, call each function ending in .return, for example pandoc.table.return. For more details, please see the official documentation in e.g. ?pandoc.strong.

The full list of currently available primitive Pandoc-related functions are:

• pandoc.indent
• pandoc.p
• pandoc.strong
• pandoc.emphasis
• pandoc.strikeout
• pandoc.verbatim
• pandoc.link
• pandoc.image
• pandoc.date
• pandoc.formula
• pandoc.footnote
• pandoc.horizontal.rule
• pandoc.header
• pandoc.title

<a id="lists"></a> For example there is a helper function rendering R lists into markdown:

> l <- list(
+        "First list element",
+        paste0(1:5, '. subelement'),
+        "Second element",
+        list('F', 'B', 'I', c('phone', 'pad', 'talics')))
> pandoc.list(l, 'roman')

Which command produces the following output:

I. First list element
    I. 1. subelement
    II. 2. subelement
    III. 3. subelement
    IV. 4. subelement
    V. 5. subelement
II. Second element
    I. F
    II. B
    III. I
        I. phone
        II. pad
        III. talics

<!-- end of list -->

<a id="tables"></a>

Markdown tables

One of the most popular feature in pander is pandoc.table, rendering most tabular R objects into markdown tables with various options and settings (e.g. style, caption, cell highlighting, cell alignment, width). This section aims to provide quick introduction to most common options, but for more usage/implementation details and examples, please refer to specialized vignette, which can be accessed by vignette('pandoc_table') or available online here.

Let's start with a small example:

> pandoc.table(mtcars[1:3, 1:4])

Which command produces the following output by default:

-------------------------------------------
                mpg   cyl   disp   hp
------------------- ----- ----- ------ ----
   **Mazda RX4**     21     6    160   110

 **Mazda RX4 Wag**   21     6    160   110

  **Datsun 710**    22.8    4    108    93
-------------------------------------------

<a id="style"></a><a id="styles"></a>

Please note that all below features are also supported by the more concise pander generic S3 method!

Formats

All four Pandoc formats are supported by pander. From those (multiline, simple, grid, pipe/rmarkdown), I'd suggest sticking to the default multiline format with the most features, except when using rmarkdown v1.0 or jupyter notebook, where multiline is not supported (for this end the default table format is rmarkdown when pander is called inside of a jupyter notebook). Please see a few examples below:

<a id="multiline-table"></a>

The default style is the multiline format (except for calling pander inside of a of a jupyter notebook) as most features (e.g. multi-line cells and alignment) are supported:

> m <- mtcars[1:2, 1:3]
> pandoc.table(m)

--------------------------------------
      &nbsp;         mpg   cyl   disp
------------------- ----- ----- ------
   **Mazda RX4**     21     6    160

 **Mazda RX4 Wag**   21     6    160
--------------------------------------

While simple tables are much more compact, but do not support line breaks in cells:

> pandoc.table(m, style = "simple")

                mpg   cyl   disp
------------------- ----- ----- ------
   **Mazda RX4**     21     6    160
 **Mazda RX4 Wag**   21     6    160

My personal favorite, the grid format is really handy for emacs users and it does support line breaks inside of cells, but cell alignment is not possible in most parsers:

> pandoc.table(m, style = "grid")

+---------------------+-------+-------+--------+
|                |  mpg  |  cyl  |  disp  |
+=====================+=======+=======+========+
|    **Mazda RX4**    |  21   |   6   |  160   |
+---------------------+-------+-------+--------+
|  **Mazda RX4 Wag**  |  21   |   6   |  160   |
+---------------------+-------+-------+--------+

And the so called rmarkdown or pipe table format i