So far you've seen R Markdown used to produce long-format HTML documents. But there are many other types of output that you can make. This chapter gives a brief overview of some of the most important alternate formats. Even more are available in add-on packages, some of which are listed at <http://rmarkdown.rstudio.com/formats.html> (or will be by the time the book is published).
RStudio's knit button renders a file to the first format listed in its `output` field. You can render to additional formats by clicking the dropdown menu beside the knit button.
Each output format is an R function. If you don't specify a package, the default is assumed to be `rmarkdown`. That means you can get help about the parameters to the format with, e.g., `?rmarkdown:html_document()`
You can customize a format, pass arguments to the output function as sub-values of the `output` field. For example, we can change [1-example.Rmd](http://github.com/hadley/r4ds/tree/master/rmarkdown-demos/1-example.Rmd) to render with a floating table of contents,
The previous chapter focussed on the default `html_document` output. There are number of basic variations on that theme, generating different types of documents:
Remember, when generating a document to share with decision makes, you can turn off the default display of code by setting global options in the setup chunk:
Notebooks are a variation on documents. The rendered output of the HTML notebook, `html_notebook`, is very similar to the rendered output of the HTML document, `html_document`. The difference is in the purpose: a document is focussed on communicating with decisions makers, while a notebook is focussed on collaborating with other data scientists. The difference in goals leads to storing different things in the HTML output. Both HTML outputs will contain the fully rendered output, but the notebook also contains the full source code. That means you can use the `.nb.html` generated by the notebook in two ways:
Emailing `.nb.html` files is a simple way to share analyses with your colleagues. The main problem will then be integrating their changes with yours. If this starts to happen a lot, you will soon want to learn Git and Github because it makes collaboration much easier. As mentioned early, Git & GitHub is outside the scope of the book, but there's one tip that's useful if you're already using them: use both `html_notebook` and `github_document` outputs.
`html_notebook` gives you a local preview, and a file that you can share via email. `github_document` creates a minimal md file that is easily diffed, and that GitHub will render for you. Checking in the rendered results of a data analysis is good practice because it makes it very easy to see what has changed between runs of an analysis.
You can also use R Markdown to produce presentations. You get less visual control that with a tool like Keynote or Powerpoint, but automatically inserting the results of your R code into a presentation can save a huge amount of time. Presentations work by dividig your content into slides, with a new slide beginning at each first (`#`) or second (`##`) level header. You can also insert a horizontal rule (`***`) to create a new slide without a header.
Dashboards are a useful way to communicate large amounts of information visually and quickly. Flexdashboard makes it particularly easy to create dashboards using R Markdown and a convention for how the headers affect the layout:
Flexdashboard also provides simple tools for creating sidebars, tabsets, value boxes, and gauges. To learn more about flexdashboard visit <http://rmarkdown.rstudio.com/flexdashboard/>.
HTML is an interactive format, and you can take advantage of that interactivity with __htmlwidgets__, R functions that produce interactivce html visualizations. For example, take the __leaflet__ map below. If you're viewing this page on the web, you can drag the map around, zoom in and out, etc. You obviously can't do that on a book, so rmarkdown automatically inserts a static screenshot for you.
The great thing about htmlwidgets is that you don't need to know anything about HTML or javascipt to use them. All the details are wrapped inside the package so you don't need to worry about it.
* __threejs__, <https://github.com/bwlewis/rthreejs> for interactive 3d plots.
* __DiagrammeR__, <http://rich-iannone.github.io/DiagrammeR/> for diagrams
(like flow charts and simple node-link digrams).
To learn more about htmlwidgets and see a more complete list of packages that provide them visit <http://www.htmlwidgets.org/>.
### Shiny
htmlwidgets provide __client-side__ interactivity --- all the interactive happens in the browser, independently of R. On one hand, that's great because you can distribute the HTML file without any connection to R. However, that fundamentally limits what you can do to things that have been implemented in HTML and javascript. An alternative approach is to use __shiny__, a package that allows you to creative interactivity using R code, not javascript.
To call Shiny code from an R Markdown document, add `runtime: shiny` to the header:
```yaml
title: "Shiny Web App"
output: html_document
runtime: shiny
```
Then you can use the "input" functions to add interactive components to the document:
```{r, message = FALSE, collapse = FALSE}
library(shiny)
textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)
You can then refer to them in your document as `input$name` and `input$age`, and the code that uses will be automatically re-run. This is a bit of simplification, but in essence, the job of shiny is to figure out the minimal amount of code that needs to be rerun when the inputs change.
I can't show you a live shiny app here because shiny interations occur on the __server-side__. This means you can write interactive apps without knowing javascript, but it means that you need a server to run it on. This introduces a logistical issue: Shiny apps need a Shiny server to be run online. When you run shiny apps on your own computer, shiny automatically sets up a shiny server for you, but you need a public facing shiny server if you want to publish this sort of interactivity online. That's the fundamental trade-off of shiny: you can do anything in a shiny document that you can do in R, but it that requires someone to be running R.
Learn more about Shiny <http://shiny.rstudio.com/>.
## Websites
With a little additional infrastructure you can use R Markdown to generate a complete website. Once you have multiple document in a single directory, you can `rmarkdown::render_site()` to render them all simultaneously. A few other files provide additional control:
* a YAML file named `_site.yml` provides the navigation for the site, e.g.
* a .Rmd file named `index.Rmd` provides the content for the home page of
your website
Execute `rmarkdown::render_site()` to build `_site`, a directory of files ready to deploy as a standalone static website, or if you use an RStudio Project for your website directory. RStudio will add a Build tab to the IDE that you can use to build and preview your site.
Read more at <http://rmarkdown.rstudio.com/rmarkdown_websites.html>.
* The __prettydoc__ package, <https://github.com/yixuan/prettydoc/>,
provides lightweight document formats with a range of attractive
themes.
* The __rticles__ package, <https://github.com/rstudio/rticles>, compiles a
selection of formats tailored for specific scientific journals.
See <http://rmarkdown.rstudio.com/formats.html> for a list of even more formats. You can also create your own by following the instructions at <http://rmarkdown.rstudio.com/developer_custom_formats.html>.
