R Markdown installation for Linux
Problem
You want to use R Markdown. How to install it?
(Inside R Markdown, you can embed Python too. Actually, that’s what I want to use.)
Solution
First, you must have R:
$ sudo apt install r-base-core
Make sure that it’s installed correctly. Start the R shell with the command “R
“. Exit with Ctrl+d.
Install RStudio (optional, but recommended):
- visit https://www.rstudio.com/products/rstudio/
- download RStudio Desktop and install it
Launch RStudio. Select File -> New File -> R Markdown… RStudio will offer to install a lot of packages that are necessary for working with .Rmd files. Select Yes and let it work. It’ll take a few minutes.
To have Python support, install the package “reticulate”. Enter the following in the R shell:
> install.packages("reticulate")
Visual Studio Code support
For working with .Rmd files, you don’t have to use R Studio. Personally, I prefer VS Code. To have R support, install the extension “R” by Yuki Ueda. It provides syntax highlighting for .Rmd files and lots of other goodies.
This VS Code extension requires the R package “‘languageserver”. Install it in the R shell:
> install.packages("languageserver")
For the first time it failed for me. It turned out that the Ubuntu package libcurl-dev
was missing. This is a metapackage and I had to install the package libcurl4-openssl-dev
. After this, install.packages("languageserver")
in the R shell succeeded.
Restart VS Code, open an .Rmd file and now everything should be OK. Right click on the file name, select Open Preview, and you should see the rendered output.
Examples
See here: https://github.com/jabbalaci/blog-assets/tree/master/20210929-Rmd
Update (20211018)
VS Code is great, but it doesn’t update the PDF. When you open a preview, it generates a temporary HTML output. If you want to update the PDF output automatically, read this post of mine.
Update (20211216)
After a system update, I got an error that some .so
file was missing. In this case, launch R and issue the command “update.packages()
“. This command updates all installed packages.
If you get a warning that some packages won’t be updated, try this: “update.packages(oldPkgs = old.packages())
“.
I also got a warning that the permission of /usr/lib/R/library
is not OK. I launched R as a normal user and I had no write permission on this folder. I changed the owner of this folder to my normal user and the issue got solved.
Update (20230128) — Installing under Manjaro Linux
I installed the whole thing on a fresh Manjaro box and here are the steps I had to perform. This is a short(er) summary of everything mentioned above.
In the following, $
signifies the Bash shell and >
signifies the R shell.
Install RStudio:
$ yay -S rstudio-desktop-bin
Don’t launch it yet. Verify if R is available:
$ R
Tap Ctrl-D twice to quit the R shell.
Install these packages:
$ yay -S openssl-1.1
$ yay -S texlive-core texlive-latexextra
$ yay -S gcc-fortran
$ yay -S pandoc
$ yay -S tk
$ yay -S okular
Modify the owner of /usr/lib/R/library
to make it writable by you:
$ cd /usr/lib/R
$ sudo chown -R {user}:{group} library/
Where {user}
is your username and {group}
is your group. The value of the two may be the same.
Start RStudio:
$ /usr/lib/rstudio/rstudio &
It’s a good idea to make a launcher script for it.
In RStudio: File -> New File -> R markdown…, then choose “Yes” to install the dependencies.
RStudio will (probably) install the following R packages:
- base64enc
- digest
- evaluate
- glue
- highr
- htmltools
- jsonlite
- knitr
- magrittr
- markdown
- mime
- rmarkdown
- stringi
- stringr
- xfun
- yaml
Install the following R packages too. Remember, now >
means the R shell:
> install.packages("reticulate")
> install.packages("Matrix")
> install.packages("languageserver")
Finally, update all R packages:
> update.packages()
If you get an error, you may have to redo this step:
$ cd /usr/lib/R
$ sudo chown -R {user}:{group} library/
Issue this command again:
> update.packages()
If everything went well, it won’t update anything (since everything is already up to date).
At the end, try to convert an .Rmd
file to PDF:
$ Rscript -e "rmarkdown::render('test.Rmd')"
It should work.
Now that everything is installed, you can remove RStudio if you want. We’ll be able to compile .Rmd
files to PDF in the command line, we won’t need RStudio for that. This step is optional:
$ yay -R rstudio-desktop-bin
Update (20230131) — Installing under Ubuntu 22.04
I installed the whole thing on a fresh Ubuntu 22.04 box too. This is a short(er) summary of everything mentioned above. Note that I had problem with installing RStudio (openssl conflict), so I skipped that part. However, RStudio is not necessary, it was just optional.
In the following, $
signifies the Bash shell and R>
signifies the R shell.
Here are the steps:
$ sudo apt install r-base r-base-dev
$ sudo apt install libxml2-dev
$ sudo apt install texlive
$ sudo apt install texlive-latex-extra
$ sudo apt install pandoc
Verify if R is available:
$ R
Tap Ctrl-D twice to quit the R shell.
Make the folder site-library/
writable:
$ cd /usr/local/lib/R
$ sudo chown -R {user}:{group} site-library/
Where {user}
is your username and {group}
is your group. The value of the two may be the same.
Install these R packages:
R> install.packages("base64enc")
R> install.packages("digest")
R> install.packages("evaluate")
R> install.packages("glue")
R> install.packages("highr")
R> install.packages("htmltools")
R> install.packages("jsonlite")
R> install.packages("knitr")
R> install.packages("magrittr")
R> install.packages("markdown")
R> install.packages("mime")
R> install.packages("rmarkdown")
R> install.packages("stringi")
R> install.packages("stringr")
R> install.packages("xfun")
R> install.packages("yaml")
R>
R> install.packages("reticulate")
R> install.packages("Matrix")
R> install.packages("languageserver")
Make these folders writable:
$ cd /usr/local/lib/R
$ sudo chown -R {user}:{group} site-library/
$ cd /usr/lib/R
$ sudo chown -R {user}:{group} library/
Update all the R packages:
R> update.packages()
Finally, try to convert an .Rmd
file to PDF:
$ Rscript -e "rmarkdown::render('test.Rmd')"
It should work.
Acknowledgement
I would like to say thanks to my students, Erik Pál and Antal Svec for their help for testing the installation process under Manjaro and Ubuntu.
Links
markdown to LaTeX
See https://pandoc.org/try/ . It’s an online service, worked well for me.
It supports tons of formats. You can convert from anything to anything. It’s just a web interface for the command pandoc, but if you need a quick solution, use this web interface.
You can open a markdown (.md) file in Okular
Today I found out by accident that you can open a markdown file (.md
) with okular. okular was just a PDF viewer for me. The .md
file is nicely rendered and you can convert it to PDF or you can print it. Awesome!
Remarkable: a nice markdown editor with live preview
Update (20150820): I found a better solution. Check out the last update at the end of this post.
At last a cool markdown editor with live preview. Check it out here: http://remarkableapp.net/index.html.
Demo
I read about it here: http://www.unixmen.com/remarkable-new-markdown-editor-linux/.
Open .md files with Midnight Commander
# markdown regex/i/\.(md|markdown) Open=remarkable %f 1>/dev/null 2>&1 &
Installing the Ruby Version Manager and some gems
Problem
I wanted to try the Ruby script redcarpet. Since I’ve never used Ruby, I had serious problems with installing it… Fortunately ndbroadbent gave me a hand and provided a step-by-step description how to get it done. So here is what I learned.
Solution
The “easiest” way is to install RVM, the Ruby Version Manager. RVM lets you run multiple versions of Ruby, and each Ruby can set up its own environment. RVM facilitates the installation of gems and takes care of all the PATH
and GEM_HOME
stuff automatically. Note that if you ever need to install any more gems, don’t use sudo anymore. Just run ‘gem install <gem_name>
‘.
Installing RVM and the redcarpet gem ($
is the prompt):
$ bash < # the installer added this line to ~/.bash_profile: # [[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # let's source it: $ source ~/.bash_profile $ rvm install 1.8.7 $ rvm use --default 1.8.7 $ gem install redcarpet
Now you should be able to run redcarpet, which is a Ruby interface to the upskirt library, the library that is used at GitHub to render markdown texts.
Alternatives
You can use the “markdown” command, which is the classical implementation of the markdown “language”, or you can also use the upskirt project, which is the reference implementation of the GitHub flavored markdown. Redcarpet is just a wrapper around upskirt.
Update: there is also a Python wrapper for upskirt called pantyshot.
README.markdown on GitHub
For a quick and painless solution check out the last update at the end of the post.
When you create a project on GitHub, it is highly encouraged to add a README file too. Thus, when someone visits your project’s page, they will see the content of your README file automatically (example).
If you want, you can use the markdown syntax in your README files. In this case don’t forget to rename the file to README.markdown
. It has the advantage that the output is much nicer while the source remains readable in a normal text editor too (example).
Update: You can also name the file as README.md
. In the future I’ll use the .md
extension, it’s shorter and simpler.
To learn more about the markdown syntax, refer to these links:
Problem
When I write a README.markdown
file, I’d like to visualize it before uploading to GitHub. If there is a problem, I don’t want to commit this file several times. I’d like to refine it on my local machine and when it’s good, I want to upload it once.
Solution
I came up with the following Python script to visualize marked up files:
import os import sys MARKDOWN = 'markdown' UPSKIRT = 'upskirt' PROGRAM = MARKDOWN VERBOSE = True def main(): update = False if len(sys.argv) < 2: print "Usage: {0} <file.markdown> [-u]".format(sys.argv[0]) sys.exit(1) # else if '-u' in sys.argv: update = True sys.argv.remove('-u') input_file = sys.argv[1] os.system("{program} {input} > /tmp/markdown.html".format(program=PROGRAM, input=input_file)) if not update: os.system("chromium-browser /tmp/markdown.html &") if VERBOSE: print >>sys.stderr, "# renderer: {0}".format(PROGRAM) ############################################################################# if __name__ == "__main__": main()
The up-to-date version of the script is available in this GitHub repository.
Usage: put it in your ~/bin
directory (make sure ~/bin
is in your PATH
), make it executable (chmod u+x ~/bin/markdown.py
), and call it as “markdown.py README.markdown
“. It will open the HTML output in a new tab. Adding the “-u
” switch (update), the HTML is not opened in the browser.
Typical usage: call it first as “markdown.py README.markdown
“, then add the “-u
” switch and refresh the output in the browser.
Ref.: I saw this idea here but I couldn’t make it work with Ruby. I added the “-u
” switch to make it easier to use.
Update (20110507)
First, I managed to install redcarpet. It was not easy… I wrote a post about it.
Second, if you want to use the GitHub flavored markdown, you don’t need to install redcarpet. I figured out later that redcarpet is just a Ruby wrapper for upskirt. So you can use upskirt directly. It’s written in C, just compile it and use the executable binary “upskirt
“. This is integrated in the new version of the script (available here).
Update (20120212)
The “upskirt” project is gone from Github. It is replaced by sundown. Sundown is a fork of upskirt and this is the version used by Github too.
Update (20120219)
As it was pointed out by Teodor in a comment, the easiest way is to use the text editor ReText. It has a live preview function (Ctrl+Shift+E
), thus editing Markdown or reStructuredTexts is made trivial. ReText is written in Python by the way.
Update (20141203)
I found an even nicer editor for markdown files: Remarkable. I write about it here.
Update (20150820)
Here is the ultimate solution :) Use the Atom editor with the markdown-preview package. Open a rendered version of the Markdown in the current editor with “Ctrl-Shift-M”.