The first thing you will notice if you try to install all the software required is the prerequisites are huge. Most of this is LaTeX which is well over 1GB.

I don’t recommend trying to install this on your base system for the following reasons:

  • Good luck getting a consistent install cross platform.

  • It will add a lot of packages to your system and if you run a rolling Linux Distro like I do you will be updating it every day.

  • If you break it you are going to be in a world of pain trying to fix it.

So the way I propose you use it is via a docker image. The nice thing about using it this way is:

  • It leaves your base system alone.
  • You can stick it up on docker hub and share it with ci like github actions.
  • If the image breaks you can go back to previous versions easily.

Docker Image

I have created an image based off Arch Linux which has the latest and greatest packages required to generate documents and I have pushed it to docker hub so its pretty easy to use.

All you need to do is make sure you have docker installed. Or if you are on Linux take a look at the arch wiki entry on it.

Rmarkdown script

Now create the following script file on your system. I recommend copying it into a location in your path so you can use it easily but you can call it via its full path if you want to.

rmd

#!/bin/bash
docpath=`realpath $1`
docker run --rm -v `pwd`:`pwd` wiltaylor/rmarkdown:latest Rscript -e "require(rmarkdown); render('$docpath')"

Now the way this document works is it will generate a document from the document passed to it. There is one big catch though, the working directory must be either the same as the target file is in or lower down in the tree. (i.e. if you add /foo/bar.txt you need to also be in the /foo directory.)

Now that you have the script setup lets create some test files.

test1.rmb

---
output: word_document
--- 

# Hello MS Word

test2.rmb

---
output: pdf_document
---

# Hello PDF

test3.rmb

# Hello HTML

And then run the following commands against them.

rmd ./test1.rmb
rmd ./test2/rmb
rmd ./test3.rmb

If everything worked you should now have a test1.docx a test2.pdf and a test3.html files.

Editor/IDE

You have a few choices here. The main one that most people will recommend is R Studio which is a full IDE specifically designed for working with R.

Personally however I just use Visual Studio Code with an RMarkdown plugin or even vim if I am in the shell. My goal was to create a workflow that let me work in the same places i code in. However feel free to use whatever you feel comfortable with.

Examples

I have also created a bunch of examples in the repo I created for the docker image which you can get to here.

RMarkdown Series