{"id":14069030,"url":"https://github.com/r-lib/roxygen2md","last_synced_at":"2025-10-11T09:17:02.388Z","repository":{"id":66205294,"uuid":"74680132","full_name":"r-lib/roxygen2md","owner":"r-lib","description":"Convert elements of roxygen documentation to markdown","archived":false,"fork":false,"pushed_at":"2025-09-04T02:25:26.000Z","size":6392,"stargazers_count":67,"open_issues_count":3,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-04T04:34:19.395Z","etag":null,"topics":["documentation","markdown","r"],"latest_commit_sha":null,"homepage":"https://roxygen2md.r-lib.org/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/r-lib.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":null,"code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2016-11-24T14:25:44.000Z","updated_at":"2025-09-04T02:26:40.000Z","dependencies_parsed_at":"2024-01-13T07:02:17.590Z","dependency_job_id":"31235d0b-c2fd-437b-aab4-9e72455f3d7c","html_url":"https://github.com/r-lib/roxygen2md","commit_stats":null,"previous_names":["r-pkgs/roxygen2md"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/r-lib/roxygen2md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Froxygen2md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Froxygen2md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Froxygen2md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Froxygen2md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/r-lib","download_url":"https://codeload.github.com/r-lib/roxygen2md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/r-lib%2Froxygen2md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279006752,"owners_count":26084177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","markdown","r"],"created_at":"2024-08-13T07:06:33.314Z","updated_at":"2025-10-11T09:17:02.354Z","avatar_url":"https://github.com/r-lib.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# roxygen2md\n\n\u003c!-- badges: start --\u003e\n[![rcc](https://github.com/r-lib/roxygen2md/workflows/rcc/badge.svg)](https://github.com/r-lib/roxygen2md/actions)\n[![Codecov test coverage](https://codecov.io/gh/r-lib/roxygen2md/branch/main/graph/badge.svg)](https://app.codecov.io/gh/r-lib/roxygen2md?branch=main)\n[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)\n[![CRAN status](https://www.r-pkg.org/badges/version/roxygen2md)](https://cran.r-project.org/package=roxygen2md)\n\u003c!-- badges: end --\u003e\n\nThe goal of roxygen2md is to replace Rd syntax with Markdown\nin your package's `roxygen2` documentation.\nThe following Rd code is converted to the Markdown equivalent:\n\n- `\\emph{}`\n- `\\bold{}` and `\\strong{}`\n- `\\href{}`\n- `\\url{}`\n- `\\code{...}`\n- Various variants of `\\code{\\link{...}}` and `\\code{\\link[...]{...}}` (only with `scope = \"full\"`, see below)\n\nIf necessary, `DESCRIPTION` is edited to enable Markdown in roxygen blocks.\nYou'll need `roxygen2` version 6.0.0 or later.\n\nCall `roxygen2md::roxygen2md()` in your package's directory, or navigate to \"Tools/Addins/Rd to Markdown\" in RStudio.\n\nThe substitutions are not completely safe, please carefully examine the results!\n\n\n## Installation\n\nInstall from CRAN using\n\n```r\ninstall.packages(\"roxygen2md\")\n```\n\nGet the latest development version from GitHub with:\n\n\n```r\n# install.packages(\"pak\", repos = sprintf(\"https://r-lib.github.io/p/pak/stable/%s/%s/%s\", .Platform$pkgType, R.Version()$os, R.Version()$arch))\npak::pak(\"r-lib/roxygen2md\")\n```\n\n\n## Usage\n\nIn your package directory, run\n\n```r\nroxygen2md::roxygen2md()\n```\n\nIf you are using RStudio, choose the item \"Rd to Markdown\" from your \"Addins\" menu.\n\nYou will be guided through the process.\n\nAt any time, choose the item \"Find Rd\" from your \"Addins\" menu, or run `find_rd()`, to enumerate Rd elements in your R scripts.\n\n\n\n## Converting large packages\n\nFor larger existing packages, a three-stage workflow is recommended, using `roxygen2md(scope = \"none\")`, `\"simple\"` and `\"full\"` in sequence:\n\n- `\"none\"` only adds `list(markdown = TRUE)` to the `Roxygen` field in `DESCRIPTION`\n- `\"simple\"` only converts elements like `\\code{}` and `\\emph{}`\n- `\"full\"` runs all conversions\n- `\"unlink\"` splits complicated `\\code{}` tags with embedded `\\link{}`\n\nThis helps isolating mostly automated changes from changes that require review.\nAfter this `find_rd()` shows remaining Rd format artifacts that were not handled by the conversion.\n\nSee https://github.com/rstudio/rmarkdown/pull/1583 for an example conversion.\n\n### Baseline\n\nAfter `roxygen2md(scope = \"none\")`, interpretation of Markdown elements is enabled.\nRunning `devtools::document()` should ideally lead to whitespace-only changes in the `.Rd` files, this can be verified with `git diff -w -- man` or with a visual diff tool like Meld or diffuse.\nMake sure that enabling of Markdown doesn't add unwanted artifacts.\n(The second commit in the example PR was necessary due to such artifacts -- the underscore has a special meaning in Markdown.)\n\n### Simple conversion\n\nRunning `roxygen2md(scope = \"simple\")` after `\"none\"` (and running `devtools::document()`) should lead to changes in R files mostly, only very few `.Rd` files should be changed.\nAgain, make sure this doesn't add unwanted artifacts.\n\n### Removing links\n\nOptionally, run `roxygen2md(scope = \"unlink\")` after `\"simple\"` (and running `devtools::document()`).\nThis replaces all instances of `\\link{...}` with `...`.\nThis isn't a valid conversion, but a helper to split up complex instances of `\\code{...\\link{...}...}` for which no easy-to-read translation to Markdown exists.\nUse a visual diff tool like Meld or diffuse to quickly iterate through all changes and keep only those that are intended.\nRun `devtools::document()` and commit if necessary.\n\nConsider inserting `@seealso` tags to link to functions instead.\nRender the documentation with [pkgdown](https://pkgdown.r-lib.org/) to take advantage of its [auto-link feature](https://pkgdown.r-lib.org/articles/linking.html) -- all functions gain automatic links without the need for further markup.\n\n### Full conversion\n\nRunning `roxygen2md()` after `scope = \"simple\"` (and running `devtools::document()`) converts all `\\link{}` expressions.\nThis is the trickiest part of the entire conversion.\nDue to the staged approach, the changeset is reduced to a minimum.\nReview carefully, luckily `R CMD check` catches bad links introduced in this stage.\n\n### Manual conversion\n\nThe `find_rd()` functions shows positions of Rd-like comments that were not handled by the conversion.  In RStudio, a markers pane will open.\n\n\n## Limitations\n\nThe package's `DESCRIPTION` must have its `Encoding` field set to `UTF-8` or `ASCII`:\n\n```\nEncoding: UTF-8\n```\n\nIf you use a different encoding, please recode your files with [`recode`](https://manpages.ubuntu.com/manpages/noble/man1/recode.1.html) or a similar tool and update the `Encoding` field before proceeding. Example:\n\n```sh\nrecode latin1..utf8 R/*\n```\n\nGPL-3 © Kirill Müller\n\n-----\n\n## Code of Conduct\n\nPlease note that the roxygen2md project is released with a [Contributor Code of Conduct](https://roxygen2md.r-lib.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Froxygen2md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fr-lib%2Froxygen2md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fr-lib%2Froxygen2md/lists"}