Repository files navigation

The goal of roxygen2md is to replace Rd syntax with Markdown in yourpackage’sroxygen2 documentation. The following Rd code is convertedto the Markdown equivalent:

• \emph{}
• \bold{} and\strong{}
• \href{}
• \url{}
• \code{...}
• Various variants of\code{\link{...}} and\code{\link[...]{...}}(only withscope = "full", see below)

If necessary,DESCRIPTION is edited to enable Markdown in roxygenblocks. You’ll needroxygen2 version 6.0.0 or later.

Callroxygen2md::roxygen2md() in your package’s directory, or navigateto “Tools/Addins/Rd to Markdown” in RStudio.

The substitutions are not completely safe, please carefully examine theresults!

Install from CRAN using

install.packages("roxygen2md")

Get the latest development version from GitHub with:

# install.packages("pak", repos = sprintf("https://r-lib.github.io/p/pak/stable/%s/%s/%s", .Platform$pkgType, R.Version()$os, R.Version()$arch))pak::pak("r-lib/roxygen2md")

In your package directory, run

roxygen2md::roxygen2md()

If you are using RStudio, choose the item “Rd to Markdown” from your“Addins” menu.

You will be guided through the process.

At any time, choose the item “Find Rd” from your “Addins” menu, or runfind_rd(), to enumerate Rd elements in your R scripts.

For larger existing packages, a three-stage workflow is recommended,usingroxygen2md(scope = "none"),"simple" and"full" in sequence:

• "none" only addslist(markdown = TRUE) to theRoxygen field inDESCRIPTION
• "simple" only converts elements like\code{} and\emph{}
• "full" runs all conversions
• "unlink" splits complicated\code{} tags with embedded\link{}

This helps isolating mostly automated changes from changes that requirereview. After thisfind_rd() shows remaining Rd format artifacts thatwere not handled by the conversion.

Seerstudio/rmarkdown#1583 for an exampleconversion.

Afterroxygen2md(scope = "none"), interpretation of Markdown elementsis enabled. Runningdevtools::document() should ideally lead towhitespace-only changes in the.Rd files, this can be verified withgit diff -w -- man or with a visual diff tool like Meld or diffuse.Make sure that enabling of Markdown doesn’t add unwanted artifacts. (Thesecond commit in the example PR was necessary due to such artifacts –the underscore has a special meaning in Markdown.)

Runningroxygen2md(scope = "simple") after"none" (and runningdevtools::document()) should lead to changes in R files mostly, onlyvery few.Rd files should be changed. Again, make sure this doesn’tadd unwanted artifacts.

Optionally, runroxygen2md(scope = "unlink") after"simple" (andrunningdevtools::document()). This replaces all instances of\link{...} with.... This isn’t a valid conversion, but a helper tosplit up complex instances of\code{...\link{...}...} for which noeasy-to-read translation to Markdown exists. Use a visual diff tool likeMeld or diffuse to quickly iterate through all changes and keep onlythose that are intended. Rundevtools::document() and commit ifnecessary.

Consider inserting@seealso tags to link to functions instead. Renderthe documentation withpkgdown to takeadvantage of itsauto-linkfeature – allfunctions gain automatic links without the need for further markup.

Runningroxygen2md() afterscope = "simple" (and runningdevtools::document()) converts all\link{} expressions. This is thetrickiest part of the entire conversion. Due to the staged approach, thechangeset is reduced to a minimum. Review carefully, luckilyR CMD check catches bad links introduced in this stage.

Thefind_rd() functions shows positions of Rd-like comments that werenot handled by the conversion. In RStudio, a markers pane will open.

The package’sDESCRIPTION must have itsEncoding field set toUTF-8 orASCII:

Encoding: UTF-8

If you use a different encoding, please recode your files withrecodeor a similar tool and update theEncoding field before proceeding.Example:

recode latin1..utf8 R/*

GPL-3 © Kirill Müller

Please note that the roxygen2md project is released with aContributorCode of Conduct. Bycontributing to this project, you agree to abide by its terms.