diff --git a/README.md b/README.md
index 39c8a3f..95bc8cd 100644
--- a/README.md
+++ b/README.md
@@ -23,3 +23,90 @@ to your .vimrc, source it, and execute `:PluginInstall`.
 ## Screenshot
 
 ![screenshot](http://i.imgur.com/mwr6O5t.png)
+
+## 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 "<LocalLeader>ccn" in normal mode.
+
+`" vim: set ft=help :`