R Markdown Helper

rmdh is a simple toolkit to work with R Markdown documents. It collects a bunch of small usecases like genrating, rendering or updating R Markdown documents that commonly occur (for me).

R Markdown is a format that interleaves Markdown text and R code. For a more fully-featured experience use RStudio.

Overview

rmdh implements the following subcommands:

• new: Create new R Markdown (.Rmd) document from template
• preview: Generate HTML preview
• render: Render R Markdown file
• rdata: Populate .RData as if R code in given .Rmd file would have been executed
• selfcheck: Check if R can be launched and has required packages

Use --help to get further information on the commands.

Example Usage

Creating & Rendering

# this generates the new file doc.Rmd and fills it with the template from src/template.Rmd
$ rmdh new doc.Rmd

# renders doc.Rmd and opens in browser
$ rmdh preview --watch doc.Rmd 
opening outfile at /tmp/rmdh-1z6rEyq8.html
opened
# The document is now opened in your default browser.
# You can edit doc.Rmd, and the file in the browser will get updated automatically.
# (You still have to reload manually, e.g. with F5!)

# press Ctrl+C to exit
^C

# render to doc.html
$ rmdh render doc.Rmd 
rendering doc.Rmd
done

Spawning an interactive R Shell

Assume you have an .Rmd document which sets some variables. You can populate an .Rdata file with its contents to work interactively with that state use rmdh rdata:

$ cat doc.Rmd 
---
title: "Document"
output: html_document
---

\```{r}
foo <- 3
\```

$ rmdh rdata doc.Rmd 
generating .Rdata
done

# now just open R regularly, and a session with the state of the Rmd will be loaded
$ R

R version 4.4.1 (2024-06-14) -- "Race for Your Life"
[...]

[Previously saved workspace restored]

> foo
[1] 3

Troubleshooting

rmdh works by calling the Rscript binary internally and executing R programs. Ensure that this binary work, and that you installed all required packages, including knitr and rmarkdown. rmdh selfcheck can also do this automatically for you. If everything is working, it should print:

$ rmdh selfcheck
test: launch Rscript binary...OK
test: load R packages...OK
test: rendering template document...OK
all checks passed

If this works, but your use case still does not work, please open an issue.

Installation

Binary

Statically linked packages (.deb, .rpm, .tar) and binaries for x86 and ARM are available on the releases page.

Files are signed with my key.

Via Nix (all features)

# to install permanently
nix profile install git+https://codeberg.org/tropf/rmdh

# alternatively, to get a one-off shell
nix shell git+https://codeberg.org/tropf/rmdh

Via Cargo (binary only)

cargo install --git https://codeberg.org/tropf/rmdh 

Implementation Notes

In general, this is a thin wrapper around some R functions called via Rscript. It is not checked against wonky strings, so some input might not be escaped and not behave predictably.

The installation has to copy the following items:

• rmdh binary
• completion files
• man page

Completion and man page are generated at build time by build.rs into the directory given by the environment variable GEN_ARTIFACTS. For them, the feature cli_extra has to be enabled.

License

rmdh is available under GPLv3+ (GPL-3.0-or-later).

Online

Find this project online at Codeberg.