maxygen v1.0.0

by Gabor Csardi

Markdown + Roxygen = Maxygen

Write your Roxygen documentation in Markdown.



Markdown + Roxygen = Maxygen

Linux Build Status Windows Build status CRAN RStudio mirror downloads

Write your Roxygen documentation in CommonMark Markdown. See for the complete specification.





You can use the macument() command instead of devtools::document() to create the Rd documentation from Markdown-Roxygen. macument() converts the Markdown formatting within the Roxygen comments to proper R manual format, and then calls devtools::document() itself.

See a complete example and the generated Rd files.


Inline code

Use backticks instead of \code{}:

#' @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 define ...

Code blocks

Put your code between three 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)

#' ```

### 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 `col2rgb` (in the base
#'   grDevices package).

Nested lists are also supported.


Emphasis and strong (bold) text is supported:

#' See `::is_falsy` for the definition of what is _falsy_
#' and what is _truthy_.
#' @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.

Markdown notation can be used to create links to other manual pages. There are four kinds of links:

#' Link to another manual page: [](::my_function).
#' Link to a manual page from another package: [](maxygen::macument).
#' This is a link in the text. Look at [this function](::=my_function).
#' Also look at [this function in maxygen](maxygen::macument).
#' It is possible to make text links verbatim, [`like this`](::=my_function).
#' Even if they refer to another package,
#' [`like this`](maxygen::macument).
#' With quotes: [`"like this"`](maxygen::macument).


URLs are currently not automatically recognized, but Markdown links are:

#'  This dataset is licensed under a Creative Commons
#'  Attribution-Share Alike 2.0 UK: England & Wales License,
#'  see []() for details.
#'  Please cite the reference below if you use this dataset.


Images are also recognized. The actual files must be in man/figures:

#' Here is an example plot:
#' ![](example-plot.jpg "Example Plot Title")

Bugs and glitches

  • Once macument() is called, all calls to roxygen::document() will understand the Markdown formatting.
  • Because Roxygen cannot unregister callbacks, the only way to switch back to regular Roxygen formatting is restarting R.
  • You need to explicitly include the @title, @description and @details tags in your documentation. Once this issue is fixed, this will not be necessary.
  • Please report other bugs in the issue tracker. Thanks!


MIT © Gábor Csárdi.

Functions in maxygen

Name Description
maxygen Markdown + Roxygen = Maxygen
macument Use Markdown and Roxygen to document a package
No Results!


Include our badge in your README