README.md

vim-rmarkdown

RMarkdown support for vim.

Setup

vim-rmarkdown requires

• the vim-pandoc and vim-pandoc-syntax vim plugins.

• the rmarkdown standalone package

vim-rmarkdown's repo uses the typical bundle layout, so it's very simple to install using some plugin manager such as pathogen, Vundle or NeoBundle. For example, using Vundle you should add

Plugin 'vim-pandoc/vim-rmarkdown'

to your .vimrc, source it, and execute :PluginInstall.

Screenshot

Usage

Files with the .Rmd extension are automatically detected as RMarkdown files. vim-rmarkdown loads vim-pandoc and pandoc's markdown syntax, and adds some extra functionality specific to rmarkdown.

Syntax

vim-rmarkdown extends pandoc's markdown syntax so

``` 
{r qplot, fig.width=4, message=FALSE}
library(ggplot2)
summary(cars)
qplot(speed, dist, data=cars) + 
    geom_smooth()
```

is recognized as an R code chunk, and

inline unformatted text like `r 1 + 2` 

as inline R.

R syntax is used within such fenced codeblocks and inline spans.

Command

To render the file using rmarkdown, the user can execute the |:RMarkdown| command. Its syntax is

:RMarkdown[!] [OUTPUT_TYPE] [- RENDER_ARGS[ -]] [OUTPUT_TYPE_ARGS]

OUTPUT_TYPE is one of "pdf", "word", "html", "md", "beamer", "ioslides", "revealjs", "all", or a combination thereof (e.g., "pdf+html"). Command completion is provided for defining this variable.

RENDER_ARGS are arguments passed to rmarkdown::render(...), and OUTPUT_TYPE_ARGS are passed to output objects such as rmarkdown::pdf_document(...) and rmarkdown::word_document(...). (Refer to RMarkdown's documentation). Note RENDER_ARGS MUST be surrounded by '- ' and ' -'.

The bang (!) version opens the created file on successful execution. If the execution fails, a message will be shown and a buffer will open with Rscript's output (can be dismissed by pressing q in normal mode).

:RMarkdown builds a R expression that executes rmarkdown. For example, if the current file is "input.Rmd",

:RMarkdown pdf

executes

Rscript -e 'library(rmarkdown);render("input.Rmd", "pdf_document")'

If OUTPUT_TYPE is ommited, RMarkdown produces an html document.

Some more examples:

:RMarkdown pdf latex_engine="xelatex", toc=TRUE
->
Rscript -e 'library(rmarkdown);render("input.Rmd", pdf_document(latex_engine="xelatex", toc=TRUE) 

:RMarkdown html - quiet=FALSE - toc=FALSE
->
Rscript -e 'library(rmarkdown);render("input.Rmd", html_document(toc=TRUE), quiet=FALSE)

:RMarkdown word - quiet=FALSE
->
Rscript -e 'library(rmarkdown);render("input.Rmd", "word_document", quiet=FALSE)

Note |:RMarkdown| doesn't parse the arguments itself, so the user must type them exactly as they should be used in R (for example, commas should separate arguments). For example,

:RMarkdown latex_engine="lualatex" bibliography="input.bib"

will cause rmarkdown to fail.

NrrwRgn

If the NrrwRgn plugin is available, vim-rmarkdown will register an extra command, |:RNrrw|, which "narrows" the current R chunk in a separate buffer. This command is also mapped to "ccn" in normal mode.

" vim: set ft=help :