Nothing
(R)Markdown support
In roxygen2: In-Line Documentation for R
knitr::opts_chunk$set(comment = "#>", collapse = TRUE)
We expect most roxygen2 users will write documentation using markdown rather than Rd syntax, since it's familiar, and doesn't require learning any new syntax.
In most cases, you can just use your existing RMarkdown knowledge and it'll work as you expect.
When it doesn't, you can read this vignette to figure out what's going on and how to fix it.
Enabling markdown support
To turn on Markdown support for a package, insert this entry into the DESCRIPTION file of the package:
Roxygen: list(markdown = TRUE)
If you use devtools/usethis, this will be automatically inserted for you when you create a new package.
If you're updating an existing package, we recommend usethis::use_roxygen_md() which will modify the DESCRIPTION and prompt you to use the roxygen2md package to convert your existing docs.
If needed, you can also use @md or @noMd to turn markdown support on or off for a documentation block.
Here is an example roxygen chunk that uses Markdown.
#' Use roxygen to document a package
#'
#' This function is a wrapper for the [roxygen2::roxygenize()] function from
#' the roxygen2 package. See the documentation and vignettes of
#' that package to learn how to use roxygen.
#'
#' @param pkg package description, can be path or package name. See
#' [as.package()] for more information.
#' @param clean,reload Deprecated.
#' @inheritParams roxygen2::roxygenise
#' @seealso [roxygen2::roxygenize()], `browseVignettes("roxygen2")`
#' @export
Basic syntax
roxygen uses the commonmark package, based on the "CommonMark Reference Implementation".
See https://commonmark.org/help/ for more about the parser and the markdown language it supports.
The most important details are described below.
Sections and subsections
The usual Markdown heading markup creates sections and subsections.
Top level headings (e.g. # title) create sections with the \section{} Rd tag.
This largely supersedes use of the older @section tag.
Top-level headings can 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 want put it near the end of the block, after @return for example:
#' @details
#' Trim the leading and trailing whitespace from a character vector.
#'
#' @param x Character vector.
#' @return Character vector, with the whitespace trimmed.
#'
#' @details # This will be a new section
#' ...
Top level sections are 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.
Headings at level two and above may appear inside any roxygen tag that formats lines of text, e.g. @description, @details, @return, and create subsections with the \subsection{} Rd tag.
#' @details
#' ## Subsection within details
#' ### Sub-subsection
#' ... text ...
Inline formatting
For emphasis, put the text between asterisks or underline characters.
For strong text, use two asterisks at both sides.
#' @references
#' Robert E Tarjan and Mihalis Yannakakis. (1984). Simple
#' linear-time algorithms to test chordality of graphs, test acyclicity
#' of hypergraphs, and selectively reduce acyclic hypergraphs.
#' *SIAM Journal of Computation* **13**, 566-579.
#' See `::is_falsy` for the definition of what is _falsy_
#' and what is _truthy_.
Code
Inline code is supported via backticks.
#' @param ns Optionally, a named vector giving prefix-url pairs, as
#' produced by `xml_ns`. If provided, all names will be explicitly
#' qualified with the ns prefix, i.e. if the element `bar` is defined ...
For blocks of code, put your code between triple backticks:
#' ```
#' pkg <- make_packages(
#' foo1 = { f <- function() print("hello!") ; d <- 1:10 },
#' foo2 = { f <- function() print("hello again!") ; d <- 11:20 }
#' )
#' foo1::f()
#' foo2::f()
#' foo1::d
#' foo2::d
#' dispose_packages(pkg)
#' ```
You can also include executable code chunks using the usual knitr syntax.
See below for more details.
Lists
Regular Markdown lists are recognized and converted to \enumerate{} or \itemize{} lists:
#' There are two ways to use this function:
#' 1. If its first argument is not named, then it returns a function
#' that can be used to color strings.
#' 1. If its first argument is named, then it also creates a
#' style with the given name. This style can be used in
#' `style`. One can still use the return value
#' of the function, to create a style function.
#' The style (the `...` argument) can be anything of the
#' following:
#' * An R color name, see `colors()`.
#' * A 6- or 8-digit hexa color string, e.g. `#ff0000` means
#' red. Transparency (alpha channel) values are ignored.
#' * A one-column matrix with three rows for the red, green,
#' and blue channels, as returned by [grDevices::col2rgb()].
Note that you do not have to leave an empty line before the list.
This is different from some Markdown parsers.
Tables
Use GFM table formatting:
| foo | bar |
| --- | --- |
| baz | bim |
By default, columns are left-aligned.
Use colons to generate right and center aligned columns:
| left | center | right |
| :--- | :----: | ----: |
| 1 | 2 | 3 |
Links
Markdown hyperlinks work as usual:
#' See more about the Markdown markup at the
#' [Commonmark web site](http://commonmark.org/help)
URLs inside angle brackets are also automatically converted to hyperlinks:
#' The main R web site is at <https://r-project.org>.
Images
Markdown syntax for inline images works.
The image files must be in the man/figures directory:
#' Here is an example plot:
#' 
Function links
Markdown notation can also be used to create links to other help topics.
There are two basic forms:
[topic]: The link text is automatically generated from the topic.[text][topic]: You supply the link text.
Default link text
First we explore the simplest form: [ref].
The presence of trailing parentheses, e.g., [func()], signals that the target func is a function, which causes two things to happen:
- The link text
func() is automatically typeset as code.
- The parentheses are stripped in the derived Rd link target.
+----------------------+---------------------+---------------------------------------------+
| Markdown | Links to help\ | Notes |
| | topic for ... | |
+:=====================+:====================+:============================================+
| [func()]\ | a function in same\ | Always typeset as code.\ |
| [pkg::func()] | package or in pkg | Produces Rd: \code{\link[=func]{func()}}\ |
| | | or \code{\link[pkg:func]{pkg::func()}} |
+----------------------+---------------------+---------------------------------------------+
| [thing]\ | a topic in same\ | Use for a dataset or general doc page.\ |
| [pkg::thing] | package or in pkg | Not typeset as code.\ |
| | | Produces Rd: \link{thing} or\ |
| | | \link[pkg:thing]{pkg::thing} |
+----------------------+---------------------+---------------------------------------------+
| [`thing`]\ | a topic in same\ | Same as above, but explicit backticks\ |
| [`pkg::thing`] | package or in pkg | mean that it is typeset as code.\ |
| | | Good for documenting a class.\ |
| | | Produces Rd: \code{\link{thing}} or\ |
| | | \code{\link[pkg:thing]{pkg::thing}} |
+----------------------+---------------------+---------------------------------------------+
Custom link text
Use the second form [text][ref] to link to the topic specified by ref, but with text as the link text.
+----------------------------+---------------------+-----------------------------------------+
| Markdown | Links to help\ | Notes |
| | topic for ... | |
+:===========================+:====================+:========================================+
| [text][func()]\ | a function in same\ | Text is not typeset as code.\ |
| [text][pkg::func()] | package or in pkg | Produces Rd: \link[=func]{text} or\ |
| | | \link[pkg:func]{text} |
+----------------------------+---------------------+-----------------------------------------+
| [text][thing]\ | a topic in same\ | Text is not typeset as code.\ |
| [text][pkg::thing] | package or in pkg | Use for a topic that documents NULL\ |
| | | and name is set via @name,\ |
| | | e.g., a dataset or concept.\ |
| | | Produces Rd: \link[=thing]{text} or\ |
| | | \link[pkg:thing]{text} |
+----------------------------+---------------------+-----------------------------------------+
| [`text`][thing]\ | a topic in same\ | Same as above, but explicit backticks\ |
| [`text`][pkg::thing] | package or in pkg | mean that text is typeset as code.\ |
| | | Produces Rd: \code{\link{=thing}} or\ |
| | | \code{\link[pkg:thing]{pkg::thing}} |
+----------------------------+---------------------+-----------------------------------------+
Operators
Links to operators or objects that contain special characters do not currently work.
So to link to (e.g.) the %>% operator in the magrittr package, instead of [magrittr::%>%], you will need to use the Rd notation: \code{\link[magrittr]{\%>\%}}.
Code chunks
You can insert executable code with ```r, just like in knitr documents.
For example:
simple_fenced <- "#' @title Title
#' @details Details
#' ```r
#' 1+1
#' ```
#' @md
foo <- function() NULL
"
becomes:
cat(
"\x60\x60\x60rd\n",
format(roxygen2:::roc_proc_text(roxygen2::rd_roclet(), simple_fenced)[[1]]),
"\n\x60\x60\x60"
)
This code is run every time you call roxygenize() (or devtools::document()) to generate the Rd files.
This potentially makes roxygenize() (much) slower.
Either avoid expensive computations, or turn on knitr caching with cache = TRUE.
Make sure to omit the cache from the package with usethis::use_build_ignore().
Note that knitr will call the appropriate print() or (if available) knitr::knit_print() method on the result.
This may generate markdown not supported by roxygen2.
If needed, override the automatic methods to have your R calls return your own markdown as a character vector, wrapped in knitr::asis_output().
Chunk options
Code blocks support some knitr chunk options, e.g. to keep the output of several expressions together, you can specify results="hold":
#' ```r
#' names(mtcars)
#' nrow(mtcars)
#' ```
Some knitr chunk options are reset at the start of every code block, so if you want to change these, you'll have to specify them for every chunk.
These are currently r paste0("\x60", names(roxygen2:::knitr_chunk_defaults()), "\x60").
Alternatively, you can set the knitr_chunk_options option to override these defaults, or add new chunk options that are used for the whole package.
See ?load_options for specifying roxygen2 options.
Images
Plots will create .png files in the man/figures directory with file names coming from the chunk name.
Be aware that plots can quickly increase the size of your package leading to challenges for CRAN submission.
#' ```r
#' pairs(iris[1:4], main = "Anderson's Iris Data -- 3 species",
#' pch = 21, bg = c("red", "green3", "blue")[unclass(iris$Species)])
#' ```
By default roxygen2 only includes PDF images in the PDF manual, and SVG images in the HTML manual.
If you want to avoid this restriction, set the restrict_image_formats roxygen2 option to FALSE, see ?load_options.
Possible problems
Some Rd tags can't contain markdown
When mixing Rd and Markdown notation, most Rd tags may contain Markdown markup, the ones that can not are: r paste0("\x60", roxygen2:::escaped_for_md, "\x60", collapse = ", ").
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 white space
Leading white space is interpreted by the commonmark parser, but is ignored by the Rd parser (except in \preformatted{}).
Make sure that you only include leading white space intentionally, for example, in 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 white space:
#' You can see more about this topic in the book cited below, on page
#' 42. Clearly, the numbered list that starts here is not intentional.
Try the roxygen2 package in your browser
Any scripts or data that you put into this service are public.
roxygen2 documentation built on June 28, 2024, 9:11 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::opts_chunk$set(comment = "#>", collapse = TRUE)
We expect most roxygen2 users will write documentation using markdown rather than Rd syntax, since it's familiar, and doesn't require learning any new syntax. In most cases, you can just use your existing RMarkdown knowledge and it'll work as you expect. When it doesn't, you can read this vignette to figure out what's going on and how to fix it.
Enabling markdown support
To turn on Markdown support for a package, insert this entry into the DESCRIPTION file of the package:
Roxygen: list(markdown = TRUE)
If you use devtools/usethis, this will be automatically inserted for you when you create a new package.
If you're updating an existing package, we recommend usethis::use_roxygen_md() which will modify the DESCRIPTION and prompt you to use the roxygen2md package to convert your existing docs.
If needed, you can also use @md or @noMd to turn markdown support on or off for a documentation block.
Here is an example roxygen chunk that uses Markdown.
#' Use roxygen to document a package #' #' This function is a wrapper for the [roxygen2::roxygenize()] function from #' the roxygen2 package. See the documentation and vignettes of #' that package to learn how to use roxygen. #' #' @param pkg package description, can be path or package name. See #' [as.package()] for more information. #' @param clean,reload Deprecated. #' @inheritParams roxygen2::roxygenise #' @seealso [roxygen2::roxygenize()], `browseVignettes("roxygen2")` #' @export
Basic syntax
roxygen uses the commonmark package, based on the "CommonMark Reference Implementation". See https://commonmark.org/help/ for more about the parser and the markdown language it supports. The most important details are described below.
Sections and subsections
The usual Markdown heading markup creates sections and subsections.
Top level headings (e.g. # title) create sections with the \section{} Rd tag.
This largely supersedes use of the older @section tag.
Top-level headings can 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 want put it near the end of the block, after @return for example:
#' @details #' Trim the leading and trailing whitespace from a character vector. #' #' @param x Character vector. #' @return Character vector, with the whitespace trimmed. #' #' @details # This will be a new section #' ...
Top level sections are 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.
Headings at level two and above may appear inside any roxygen tag that formats lines of text, e.g. @description, @details, @return, and create subsections with the \subsection{} Rd tag.
#' @details #' ## Subsection within details #' ### Sub-subsection #' ... text ...
Inline formatting
For emphasis, put the text between asterisks or underline characters. For strong text, use two asterisks at both sides.
#' @references #' Robert E Tarjan and Mihalis Yannakakis. (1984). Simple #' linear-time algorithms to test chordality of graphs, test acyclicity #' of hypergraphs, and selectively reduce acyclic hypergraphs. #' *SIAM Journal of Computation* **13**, 566-579.
#' See `::is_falsy` for the definition of what is _falsy_ #' and what is _truthy_.
Code
Inline code is supported via backticks.
#' @param ns Optionally, a named vector giving prefix-url pairs, as #' produced by `xml_ns`. If provided, all names will be explicitly #' qualified with the ns prefix, i.e. if the element `bar` is defined ...
For blocks of code, put your code between triple backticks:
#' ``` #' pkg <- make_packages( #' foo1 = { f <- function() print("hello!") ; d <- 1:10 }, #' foo2 = { f <- function() print("hello again!") ; d <- 11:20 } #' ) #' foo1::f() #' foo2::f() #' foo1::d #' foo2::d #' dispose_packages(pkg) #' ```
You can also include executable code chunks using the usual knitr syntax. See below for more details.
Lists
Regular Markdown lists are recognized and converted to \enumerate{} or \itemize{} lists:
#' There are two ways to use this function: #' 1. If its first argument is not named, then it returns a function #' that can be used to color strings. #' 1. If its first argument is named, then it also creates a #' style with the given name. This style can be used in #' `style`. One can still use the return value #' of the function, to create a style function.
#' The style (the `...` argument) can be anything of the #' following: #' * An R color name, see `colors()`. #' * A 6- or 8-digit hexa color string, e.g. `#ff0000` means #' red. Transparency (alpha channel) values are ignored. #' * A one-column matrix with three rows for the red, green, #' and blue channels, as returned by [grDevices::col2rgb()].
Note that you do not have to leave an empty line before the list. This is different from some Markdown parsers.
Tables
Use GFM table formatting:
| foo | bar | | --- | --- | | baz | bim |
By default, columns are left-aligned. Use colons to generate right and center aligned columns:
| left | center | right | | :--- | :----: | ----: | | 1 | 2 | 3 |
Links
Markdown hyperlinks work as usual:
#' See more about the Markdown markup at the #' [Commonmark web site](http://commonmark.org/help)
URLs inside angle brackets are also automatically converted to hyperlinks:
#' The main R web site is at <https://r-project.org>.
Images
Markdown syntax for inline images works.
The image files must be in the man/figures directory:
#' Here is an example plot: #' 
Function links
Markdown notation can also be used to create links to other help topics. There are two basic forms:
[topic]: The link text is automatically generated from the topic.[text][topic]: You supply the link text.
Default link text
First we explore the simplest form: [ref].
The presence of trailing parentheses, e.g., [func()], signals that the target func is a function, which causes two things to happen:
- The link text
func()is automatically typeset as code. - The parentheses are stripped in the derived Rd link target.
+----------------------+---------------------+---------------------------------------------+
| Markdown | Links to help\ | Notes |
| | topic for ... | |
+:=====================+:====================+:============================================+
| [func()]\ | a function in same\ | Always typeset as code.\ |
| [pkg::func()] | package or in pkg | Produces Rd: \code{\link[=func]{func()}}\ |
| | | or \code{\link[pkg:func]{pkg::func()}} |
+----------------------+---------------------+---------------------------------------------+
| [thing]\ | a topic in same\ | Use for a dataset or general doc page.\ |
| [pkg::thing] | package or in pkg | Not typeset as code.\ |
| | | Produces Rd: \link{thing} or\ |
| | | \link[pkg:thing]{pkg::thing} |
+----------------------+---------------------+---------------------------------------------+
| [`thing`]\ | a topic in same\ | Same as above, but explicit backticks\ |
| [`pkg::thing`] | package or in pkg | mean that it is typeset as code.\ |
| | | Good for documenting a class.\ |
| | | Produces Rd: \code{\link{thing}} or\ |
| | | \code{\link[pkg:thing]{pkg::thing}} |
+----------------------+---------------------+---------------------------------------------+
Custom link text
Use the second form [text][ref] to link to the topic specified by ref, but with text as the link text.
+----------------------------+---------------------+-----------------------------------------+
| Markdown | Links to help\ | Notes |
| | topic for ... | |
+:===========================+:====================+:========================================+
| [text][func()]\ | a function in same\ | Text is not typeset as code.\ |
| [text][pkg::func()] | package or in pkg | Produces Rd: \link[=func]{text} or\ |
| | | \link[pkg:func]{text} |
+----------------------------+---------------------+-----------------------------------------+
| [text][thing]\ | a topic in same\ | Text is not typeset as code.\ |
| [text][pkg::thing] | package or in pkg | Use for a topic that documents NULL\ |
| | | and name is set via @name,\ |
| | | e.g., a dataset or concept.\ |
| | | Produces Rd: \link[=thing]{text} or\ |
| | | \link[pkg:thing]{text} |
+----------------------------+---------------------+-----------------------------------------+
| [`text`][thing]\ | a topic in same\ | Same as above, but explicit backticks\ |
| [`text`][pkg::thing] | package or in pkg | mean that text is typeset as code.\ |
| | | Produces Rd: \code{\link{=thing}} or\ |
| | | \code{\link[pkg:thing]{pkg::thing}} |
+----------------------------+---------------------+-----------------------------------------+
Operators
Links to operators or objects that contain special characters do not currently work.
So to link to (e.g.) the %>% operator in the magrittr package, instead of [magrittr::%>%], you will need to use the Rd notation: \code{\link[magrittr]{\%>\%}}.
Code chunks
You can insert executable code with ```r, just like in knitr documents.
For example:
simple_fenced <- "#' @title Title #' @details Details #' ```r #' 1+1 #' ``` #' @md foo <- function() NULL "
becomes:
cat( "\x60\x60\x60rd\n", format(roxygen2:::roc_proc_text(roxygen2::rd_roclet(), simple_fenced)[[1]]), "\n\x60\x60\x60" )
This code is run every time you call roxygenize() (or devtools::document()) to generate the Rd files.
This potentially makes roxygenize() (much) slower.
Either avoid expensive computations, or turn on knitr caching with cache = TRUE.
Make sure to omit the cache from the package with usethis::use_build_ignore().
Note that knitr will call the appropriate print() or (if available) knitr::knit_print() method on the result.
This may generate markdown not supported by roxygen2.
If needed, override the automatic methods to have your R calls return your own markdown as a character vector, wrapped in knitr::asis_output().
Chunk options
Code blocks support some knitr chunk options, e.g. to keep the output of several expressions together, you can specify results="hold":
#' ```r #' names(mtcars) #' nrow(mtcars) #' ```
Some knitr chunk options are reset at the start of every code block, so if you want to change these, you'll have to specify them for every chunk.
These are currently r paste0("\x60", names(roxygen2:::knitr_chunk_defaults()), "\x60").
Alternatively, you can set the knitr_chunk_options option to override these defaults, or add new chunk options that are used for the whole package.
See ?load_options for specifying roxygen2 options.
Images
Plots will create .png files in the man/figures directory with file names coming from the chunk name.
Be aware that plots can quickly increase the size of your package leading to challenges for CRAN submission.
#' ```r #' pairs(iris[1:4], main = "Anderson's Iris Data -- 3 species", #' pch = 21, bg = c("red", "green3", "blue")[unclass(iris$Species)]) #' ```
By default roxygen2 only includes PDF images in the PDF manual, and SVG images in the HTML manual.
If you want to avoid this restriction, set the restrict_image_formats roxygen2 option to FALSE, see ?load_options.
Possible problems
Some Rd tags can't contain markdown
When mixing Rd and Markdown notation, most Rd tags may contain Markdown markup, the ones that can not are: r paste0("\x60", roxygen2:::escaped_for_md, "\x60", collapse = ", ").
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 white space
Leading white space is interpreted by the commonmark parser, but is ignored by the Rd parser (except in \preformatted{}).
Make sure that you only include leading white space intentionally, for example, in 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 white space:
#' You can see more about this topic in the book cited below, on page #' 42. Clearly, the numbered list that starts here is not intentional.
Try the roxygen2 package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.