1### Overview 2 3[![Build Status](https://travis-ci.org/rstudio/rmarkdown.svg?branch=master)](https://travis-ci.org/rstudio/rmarkdown) 4 5The **rmarkdown** package is a next generation implementation of R Markdown based on [pandoc](http://johnmacfarlane.net/pandoc/). This implementation brings many enhancements to R Markdown, including: 6 7- Create HTML, PDF, and MS Word documents as well as [Beamer](https://bitbucket.org/rivanvx/beamer/wiki/Home), [ioslides](https://code.google.com/p/io-2012-slides/), and [Slidy](http://www.w3.org/Talks/Tools/Slidy2/) presentations. 8- New markdown syntax including expanded support for tables, definition lists, and bibliographies. 9- Hooks for customizing HTML and PDF output (include CSS, headers, and footers). 10- Include raw LaTeX within markdown for advanced customization of PDF output. 11- Compile HTML, PDF, or MS Word notebooks from R scripts. 12- Extensibility: easily define new formats for custom publishing requirements. 13- Create interactive R Markdown documents using Shiny. 14 15Note that PDF output (including Beamer slides) requires an installation of TeX. 16 17See the [R Markdown documentation](http://rmarkdown.rstudio.com/) for full details. 18 19### Installation 20 21If you are working within RStudio then you can simply install the [current release](http://www.rstudio.com/ide/download/preview) of RStudio (both the rmarkdown package and pandoc are included). 22 23If you want to use the rmarkdown package outside of RStudio then you can install the package from CRAN as follows: 24 25```r 26install.packages("rmarkdown") 27``` 28 29A recent version of pandoc (>= 1.12.3) is also required. See the [pandoc installation instructions](PANDOC.md) for details on installing pandoc for your platform. 30 31### Usage 32 33The `render` function is used to convert R Markdown (Rmd) files into various output formats (the default is HTML). Calling `render` will knit the specified input document and then produce the final output document using pandoc: 34 35```r 36render("input.Rmd") 37``` 38 39You can also specify a plain markdown file in which case knitting will be bypassed: 40 41```r 42render("input.md") 43``` 44 45#### Output Formats 46 47R Markdown documents can contain a metadata section that includes both title, author, and date information as well as options for customizing output. For example, this metadata included at the top of an Rmd file adds a table of contents and chooses a different HTML theme: 48 49```yaml 50--- 51title: "Sample Document" 52output: 53 html_document: 54 toc: true 55 theme: united 56--- 57``` 58 59R Markdown has built in support for several output formats (HTML, PDF, and MS Word documents as well as Beamer presentations). These formats can also be specified in metadata, for example: 60 61```yaml 62--- 63title: "Sample Document" 64output: 65 pdf_document: 66 toc: true 67 highlight: zenburn 68--- 69``` 70 71If you aren't specifying format options you can also just use a simple format name: 72 73```yaml 74--- 75title: "Sample Document" 76output: pdf_document 77--- 78``` 79 80Multiple formats can be specified in metadata: 81 82```yaml 83--- 84title: "Sample Document" 85output: 86 html_document: 87 toc: true 88 theme: united 89 pdf_document: 90 toc: true 91 highlight: zenburn 92--- 93``` 94 95To select from the various formats defined you can pass a format name to `render`. For example: 96 97```r 98render("input.Rmd", "pdf_document") 99``` 100 101If no explicit format name is passed to `render` then the first one defined will be used. You can also render all formats defined in the file with: 102 103```r 104render("input.Rmd", "all") 105``` 106 107#### Shared Output Formats 108 109You can also define output formats externally in a file named `_output.yml` located in the same directory as the R Markdown source file. For example: 110 111```yaml 112html_document: 113 toc: true 114 theme: united 115pdf_document: 116 toc: true 117 highlight: zenburn 118``` 119 120Using an `_output.yml` file is a good way to share output settings across multiple R Markdown files in the same directory. 121 122#### Output Format Functions 123 124Output formats need not be specified in metadata. In fact, metadata is just a convenient way to invoke functions that implement output formats. There are seven built-in output formats each exported as a function from the package: 125 126- `html_document` 127- `pdf_document` 128- `word_document` 129- `md_document` 130- `beamer_presentation` 131- `ioslides_presentation` 132- `slidy_presentation` 133 134As you'd expect, these functions can also be invoked as part of the call to `render`, for example: 135 136```r 137render("input.Rmd", html_document(toc = TRUE)) 138render("input.Rmd", pdf_document(latex_engine = "lualatex")) 139render("input.Rmd", beamer_presentation(incremental = TRUE)) 140``` 141 142For more details on the options available for each format see their respective help topics. 143 144### License 145 146The **rmarkdown** package is licensed under the GPLv3 (<http://www.gnu.org/licenses/gpl.html>). 147