Introduction

Starting from version 6.0.0, roxygen supports markdown markup within most roxygen tags. Roxygen uses the commonmark package, which is based on the CommonMark Reference Implementation to parse these tags. See https://commonmark.org/help/ for more about the parser and the markdown language it supports.

Turning on markdown support

There are two ways to turn on markdown support for a package: globally, at the package level, and locally at the block level.

To turn on markdown for the whole package, insert this entry into the DESCRIPTION file of the package:

Roxygen: list(markdown = TRUE)

The position of the entry in the file does not matter. After this, all Roxygen documentation will be parsed as markdown.

Alternatively, you can use the @md tag to turn on markdown support for a single documentation chunk. This is a good option to write any new documentation for existing packages in markdown.

There is also a new @noMd tag. Use this if you turned on markdown parsing globally, but need to avoid it for a single chunk. This tag is handy if the markdown parser interferes with more complex Rd syntax.

Here is an example roxygen chunk that uses markdown.

Syntax

Sections

The usual markdown heading markup creates sections and subsections. Top level headings, i.e. ‘#’ create sections, via the \section{} Rd tag. ‘#’ may only appear after the @description and @details tags. Since @details can appear multiple times in a block, you can always precede a ‘#’ section with @details, if you prefer to place it towards the end of the block, after @return for example:

Top level sections are always placed at a fixed position in the manual page, after the parameters and the details, but before \note{}, \seealso{} and the \examples{}. Their order will be the same as in the roxygen block.

Subsections

Headings at level two and above may appear inside any roxygen tag that formats lines of text. E.g. @description, @details, @return, etc. They create subsections, via the \subsection{} Rd tag. They are allowed within top level sections as well, i.e. after ‘#’. Subsections can be nested. Example:

Tables

Use GFM table formatting:

By default, columns are left-aligned. Use colons to generate right and center aligned columns:

Images

Markdown syntax for inline images works. The image files must be in the man/figures directory:

Roxygen and Rd tags not parsed as markdown

Some of the roxygen tags are not parsed as markdown. Most of these are unlikely to contain text that needs markup, so this is not an important restriction. Tags without markdown support: @aliases, @backref, @docType, @encoding, @evalRd, @example, @examples, @family, @inheritParams, @keywords, @method @name, @md, @noMd, @noRd, @rdname, @rawRd, @usage.

When mixing Rd and markdown notation, most Rd tags may contain markdown markup, the ones that can not are: \acronym, \code, \command, \CRANpkg, \deqn, \doi, \dontrun, \dontshow, \donttest, \email, \env, \eqn, \figure, \file, \if, \ifelse, \kbd, \link, \linkS4class, \method, \newcommand, \option, \out, \packageAuthor, \packageDescription, \packageDESCRIPTION, \packageIndices, \packageMaintainer, \packageTitle, \pkg, \PR, \preformatted, \renewcommand, \S3method, \S4method, \samp, \special, \testonly, \url, \var, \verb.

Possible problems

Mixing markdown and Rd markup

Note that turning on markdown does not turn off the standard Rd syntax. We suggest that you use the regular Rd tags in a markdown roxygen chunk only if necessary. The two parsers do occasionally interact, and the markdown parser can pick up and reformat Rd syntax, causing an error, or corrupted manuals.

Leading whitespace

Leading whitespace is interpreted by the commonmark parser, whereas it is ignored by the Rd parser (except in \preformatted{}). Make sure that you only include leading whitespace intentionally, for example for nested lists.

Spurious lists

The Commonmark parser does not require an empty line before lists, and this might lead to unintended lists if a line starts with a number followed by a dot, or with an asterisk followed by whitespace:

Rd formatting

Within roxygen tags, you use .Rd syntax to format text. This vignette shows you examples of the most important commands. The full details are described in R extensions.

Note that \ and % are special characters. To insert literals, escape with a backslash: \\, \%.

Character formatting

  • \emph{italics}

  • \strong{bold}

  • \code{r_function_call(with = "arguments")}, \code{NULL}, \code{TRUE}

  • \pkg{package_name}

Mathematics

Standard LaTeX (with no extensions):

  • \eqn{a + b}: inline equation

  • \deqn{a + b}: display (block) equation

Tables

Tables are created with \tabular{}. It has two arguments:

  1. Column alignment, specified by letter for each column (l = left, r = right, c = centre.)

  2. Table contents, with columns separated by \tab and rows by \cr.

The following function turns an R data frame into the correct format, adding a row consisting of the (bolded) column names and prepending each row with #' for pasting directly into the documentation.