Convert markdown to Rd, or define custom markdown conversion rules?

Question

I'm trying to write documentation for an R package in Markdown, and have it converted to an Rd file.

I guess another way to look at this is that I want a framework that recognises various markdown constructs and allows me to specify how these should be rendered, e.g.:

• `text in backticks` gets converted to \code{text in backticks}
• **text** is converted to \bold{text}
• markdown lists are converted to \itemize{...}

and so on.

Is there something that will let me do this? The pander package in R (wrapping around pandoc) looked promising, but I'm not sure that I can specify conversion rules (for example it converts backticks using \texttt and I want \code), and it also generates a complete standalone document rather than just my input snippet converted.

The markdown package for R appears to just do markdown -> HTML. It looks like it might have support for custom renderers but I'm not sure how to write one (it looks like I have to write C code?)

I'm after something like this:

convertMarkdown(myTextSnippet,
                backticks = function (txt) {
                    return(paste0('\\code{', txt, '}'))
                },
                bold = function(txt) {
                    return(paste0('\\bold{', txt, '}'))
                },
                unordered.list = function (items) {
                    itms <- paste('\\item', items, collapse='\n')
                    return(paste('\\itemize{', itms, '}', sep='\n'))
                },
                # ... and so on
)

Does such a thing exist?

(Bonus: I just want to be able to embed markdown in my roxygen comments, so was thinking of converting parts of the comments from markdown to rd, and then running roxygen on the output).

Answer 1

Have you seen the maxygen package by @gabor-csardi?

https://github.com/gaborcsardi/maxygen

It basically lets you write roxygen headers in Markdown.

[UPDATE] These changes have been incorparated to the roxygen2 package and will go out with the version 6 release. From GitHub:

Most fields can now be written using Markdown markup instead of the traditional Rd language. You can turn on Markdown globally by adding Roxygen: list(markdown = TRUE) to DESCRIPTION. The @md / @noMd tags turn Markdown parsing on / off for the given block. See the 'markdown' vignette for more details (#364, #431, #499, #506, #507), by @gaborcsardi