rmarkdown v1.13

Dynamic Documents for R

Convert R Markdown documents into a variety of formats.

Readme

Overview

Build Status Downloads from the RStudio CRAN mirror

The rmarkdown package is a next generation implementation of R Markdown based on Pandoc. This implementation brings many enhancements to R Markdown, including:

  • Create HTML, PDF, and MS Word documents as well as Beamer, ioslides, and Slidy presentations.
  • New markdown syntax including expanded support for tables, definition lists, and bibliographies.
  • Hooks for customizing HTML and PDF output (include CSS, headers, and footers).
  • Include raw LaTeX within markdown for advanced customization of PDF output.
  • Compile HTML, PDF, or MS Word notebooks from R scripts.
  • Extensibility: easily define new formats for custom publishing requirements.
  • Create interactive R Markdown documents using Shiny.

Note that PDF output (including Beamer slides) requires an installation of TeX.

See the R Markdown documentation for full details.

Installation

If you are working within RStudio then you can simply install the current release of RStudio (both the rmarkdown package and Pandoc are included).

If you want to use the rmarkdown package outside of RStudio then you can install the package from CRAN as follows:

install.packages("rmarkdown")
# or install the dev version via remotes::install_github('rstudio/rmarkdown')

A recent version of Pandoc (>= 1.12.3) is also required. See the Pandoc installation instructions for details on installing Pandoc for your platform.

Usage

The 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:

render("input.Rmd")

You can also specify a plain markdown file in which case knitting will be bypassed:

render("input.md")

Output Formats

R 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:

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
---

R 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:

---
title: "Sample Document"
output:
  pdf_document:
    toc: true
    highlight: zenburn
---

If you aren't specifying format options you can also just use a simple format name:

---
title: "Sample Document"
output: pdf_document
---

Multiple formats can be specified in metadata:

---
title: "Sample Document"
output:
  html_document:
    toc: true
    theme: united
  pdf_document:
    toc: true
    highlight: zenburn
---

To select from the various formats defined you can pass a format name to render. For example:

render("input.Rmd", "pdf_document")

If 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:

render("input.Rmd", "all")

Shared Output Formats

You 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:

html_document:
  toc: true
  theme: united
pdf_document:
  toc: true
  highlight: zenburn

Using an _output.yml file is a good way to share output settings across multiple R Markdown files in the same directory.

Output Format Functions

Output 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:

  • html_document
  • pdf_document
  • word_document
  • md_document
  • beamer_presentation
  • ioslides_presentation
  • slidy_presentation

As you'd expect, these functions can also be invoked as part of the call to render, for example:

render("input.Rmd", html_document(toc = TRUE))
render("input.Rmd", pdf_document(latex_engine = "lualatex"))
render("input.Rmd", beamer_presentation(incremental = TRUE))

For more details on the options available for each format see their respective help topics.

License

The rmarkdown package is licensed under the GPLv3 (http://www.gnu.org/licenses/gpl.html).

Functions in rmarkdown

Name Description
html_notebook Convert to an HTML notebook
html_document Convert to an HTML document
output_format Define an R Markdown output format
output_metadata The output metadata object
includes Include content within output
pandoc_available Check pandoc availability and version
pandoc_citeproc_convert Convert a bibliograpy file
render_supporting_files Render supporting files for an input document
ioslides_presentation Convert to an ioslides Presentation
render_site Render multiple documents as a website
html_document_base Base output format for HTML-based output formats
html_notebook_metadata Generate R Notebook Metadata
html_fragment Convert to an HTML fragment.
pandoc_options Pandoc options for an output format
md_document Convert to a markdown document
run Run a Shiny document
rtf_document Convert to an RTF document
metadata The YAML metadata of the current R Markdown document
knitr_options_html Knitr options for an HTML output format
knitr_options_pdf Knitr options for a PDF output format
pandoc_path_arg Transform path for passing to pandoc
render Render R Markdown
render_delayed Delay Rendering for an Expression
knit_params_ask Run a shiny application asking for parameter configuration for the given document.
knitr_options Knitr options for an output format
latex_dependency Define a LaTeX package dependency
latex-dependencies Provide common LaTeX dependencies
pandoc_convert Convert a document with pandoc
pandoc_self_contained_html Create a self-contained HTML document using pandoc.
html_notebook_output Generate R Notebook Output
pandoc_exec Get the path of the pandoc executable
powerpoint_presentation Convert to a PowerPoint presentation
rmarkdown_format R Markdown input format definition
relative_to Relative path utility function
slidy_presentation Convert to a slidy presentation
html_vignette Convert to an HTML vignette
navbar_html Create a navbar HTML file from a navbar definition
odt_document Convert to an OpenDocument Text (ODT) document
tufte_handout Tufte handout format (PDF)
parse_html_notebook Parse an HTML Notebook
pandoc_template Render a pandoc template.
pdf_document Convert to a PDF/LaTeX document
paged_table Create a table in HTML with support for paging rows and columns
shiny_prerendered_server_start_code Get the server startup code for a shiny_prerendered server instance
site_resources Determine website resource files for a directory
rmd_metadata R Markdown Metadata
pandoc_args Functions for generating pandoc command line arguments
resolve_output_format Resolve the output format for an R Markdown document
rmarkdown-package R Markdown Document Conversion
shiny_prerendered_chunk Add code to a shiny_prerendered context
shiny_prerendered_clean Clean prerendered content for the specified Rmd input file
word_document Convert to an MS Word document
yaml_front_matter Parse the YAML front matter from a file
html-dependencies Provide common HTML dependencies for R Markdown formats
draft Create a new document based on a template
default_output_format Determine the default output format for an R Markdown document
compile_notebook Compiling R scripts to a notebook
convert_ipynb Convert a Jupyter/IPython notebook to an R Markdown document
all_output_formats Determine all output formats for an R Markdown document
find_external_resources Find External Resource References
github_document Convert to GitHub Flavored Markdown
beamer_presentation Convert to a Beamer presentation
No Results!

Details

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/rmarkdown)](http://www.rdocumentation.org/packages/rmarkdown)