vignettes/markdown.Rmd
markdown.Rmd
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 http://commonmark.org/help/ for more about the parser and the markdown language it supports.
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.
#' 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
#' @md
Emphasis and strong (bold) text are supported. For emphasis, put the text between asterisks or underline characters. For strong text, use two asterisks at both sides.
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)
#' ```
Note that this is not needed in @examples
, since its contents is formatted as R code, anyway.
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()]
Nested lists are also supported.
Note that you do not have leave an empty line before the list. This is different from some markdown parsers.
Markdown hyperlinks work as usual:
URLs inside angle brackets are also automatically converted to hyperlinks:
Markdown notation can also be used to create links to other help topics. There are two basic forms:
[ref]
: The target topic and the link text are one and the same.[text][ref]
: Link text differs from the target.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:
func()
is automatically typeset as code.
[ref] examples |
Links to help topic for … |
Notes |
---|---|---|
[func()] [pkg::func()]
|
a function in same package or in pkg
|
Always typeset as code. Produces Rd: \code{\link[=func]{func()}} or \code{\link[pkg:func]{pkg::func()}}
|
[thing] [pkg::thing]
|
a topic in same package or in pkg
|
Use for a topic that documents NULL and name is setvia @name , e.g., a dataset or concept.Not typeset as code. Produces Rd: \link{thing} or\link[pkg:thing]{pkg::thing}
|
[`thing`] [`pkg::thing`]
|
a topic in same package or in pkg
|
Same as above, but explicit backticks mean that it is typeset as code. Good for documenting a class. Produces Rd: \code{\link{thing}} or\code{\link[pkg:thing]{pkg::thing} } |
Use the second form [text][ref]
to link to the topic specified by ref
, but with text
as the link text.
[text][ref] examples |
Links to help topic for … |
Notes |
---|---|---|
[text][func()] [text][pkg::func()]
|
a function in same package or in pkg
|
Text is not typeset as code. Produces Rd: \link[=func]{text} or\link[pkg:func]{text}
|
[text][thing] [text][pkg::thing]
|
a topic in same package or in pkg
|
Text is not typeset as code. 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}
|
In the [text][ref]
, the link text is treated like normal text by default.
[`text`][ref]
.It is never appropriate to use backticks around the ref
in this form.
[text][`blah-blah`]
[text][blah-blah]
S3 and S4 class not done yet
Examples | Help topic for what? |
Notes |
---|---|---|
[abc-class] [pkg::abc-class]
|
an S4 class named “abc” in same package or in pkg
|
In Rd: \linkS4class{abc} or\link[pkg:abc-class]{pkg::abc}
|
[abc][abc-class] |
*is this a thing? | ??? \link[=abc-class]{abc}
|
Rd
markupNote 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 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.