Render R Markdown

Render the input file to the specified output format using pandoc. If the input requires knitting then knit is called prior to pandoc.

render(
  input,
  output_format = NULL,
  output_file = NULL,
  output_dir = NULL,
  output_options = NULL,
  output_yaml = NULL,
  intermediates_dir = NULL,
  knit_root_dir = NULL,
  runtime = c("auto", "static", "shiny", "shinyrmd", "shiny_prerendered"),
  clean = TRUE,
  params = NULL,
  knit_meta = NULL,
  envir = parent.frame(),
  run_pandoc = TRUE,
  quiet = FALSE,
  encoding = "UTF-8"
)

Arguments

input: The input file to be rendered. This can be an R script (.R), an R Markdown document (.Rmd), or a plain markdown document.
output_format: The R Markdown output format to convert to. The option "all" will render all formats defined within the file. The option can be the name of a format (e.g. "html_document") and that will render the document to that single format. One can also use a vector of format names to render to multiple formats. Alternatively, you can pass an output format object (e.g. html_document()). If using NULL then the output format is the first one defined in the YAML frontmatter in the input file (this defaults to HTML if no format is specified there). If you pass an output format object to output_format, the options specified in the YAML header or _output.yml will be ignored and you must explicitly set all the options you want when you construct the object. If you pass a string, the output format will use the output parameters in the YAML header or _output.yml.
output_file: The name of the output file. If using NULL then the output filename will be based on filename for the input file. If a filename is provided, a path to the output file can also be provided. Note that the output_dir option allows for specifying the output file path as well, however, if also specifying the path, the directory must exist. If output_file is specified but does not have a file extension, an extension will be automatically added according to the output format. To avoid the automatic file extension, put the output_file value in I(), e.g., I('my-output').
output_dir: The output directory for the rendered output_file. This allows for a choice of an alternate directory to which the output file should be written (the default output directory of that of the input file). If a path is provided with a filename in output_file the directory specified here will take precedence. Please note that any directory path provided will create any necessary directories if they do not exist.
output_options: List of output options that can override the options specified in metadata (e.g. could be used to force self_contained or mathjax = "local"). Note that this is only valid when the output format is read from metadata (i.e. not a custom format object passed to output_format).
output_yaml: Paths to YAML files specifying output formats and their configurations. The first existing one is used. If none are found, then the function searches YAML files specified to the output_yaml top-level parameter in the YAML front matter, _output.yml or _output.yaml, and then uses the first existing one.
intermediates_dir: Intermediate files directory. If a path is specified then intermediate files will be written to that path. If NULL, intermediate files are written to the same directory as the input file.
knit_root_dir: The working directory in which to knit the document; uses knitr's root.dir knit option. If NULL then the behavior will follow the knitr default, which is to use the parent directory of the document.
runtime: The runtime target for rendering. The static option produces output intended for static files; shiny produces output suitable for use in a Shiny document (see run). The default, auto, allows the runtime target specified in the YAML metadata to take precedence, and renders for a static runtime target otherwise.
clean: Using TRUE will clean intermediate files that are created during rendering.
params: A list of named parameters that override custom params specified within the YAML front-matter (e.g. specifying a dataset to read or a date range to confine output to). Pass "ask" to start an application that helps guide parameter configuration.
knit_meta: (This option is reserved for expert use.) Metadata generated by knitr.
envir: The environment in which the code chunks are to be evaluated during knitting (can use new.env() to guarantee an empty new environment).
run_pandoc: An option for whether to run pandoc to convert Markdown output.
quiet: An option to suppress printing during rendering from knitr, pandoc command line and others. To only suppress printing of the last "Output created: " message, you can set rmarkdown.render.message to FALSE
encoding: Ignored. The encoding is always assumed to be UTF-8.

Value

When run_pandoc = TRUE, the compiled document is written into the output file, and the path of the output file is returned. When run_pandoc = FALSE, the path of the Markdown output file, with attributes knit_meta (the knitr meta data collected from code chunks) and intermediates (the intermediate files/directories generated by render()).

Details

Note that the knitr error option is set to FALSE during rendering (which is different from the knitr default value of TRUE).

For additional details on rendering R scripts see Compiling R scripts to a notebook.

If no output_format parameter is specified then the output format is read from the YAML front-matter of the input file. For example, the following YAML would yield a PDF document:


output: pdf_document

Additional format options can also be specified in metadata. For example:


output:
  pdf_document:
    toc: true
    highlight: zenburn

Multiple formats can be specified in metadata. If no output_format is passed to render then the first one defined will be used:


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

Formats specified in metadata can be any one of the built in formats (e.g. html_document, pdf_document) or a format defined in another package (e.g. pkg::custom_format).

If there is no format defined in the YAML then html_document will be used.

R Markdown

R Markdown supports all of the base pandoc markdown features as well as some optional features for compatibility with GitHub Flavored Markdown (which previous versions of R Markdown were based on). See rmarkdown_format for details.

Examples

if (FALSE) { # \dontrun{
library(rmarkdown)

# Render the default (first) format defined in the file
render("input.Rmd")

# Render all formats defined in the file
render("input.Rmd", "all")

# Render a single format, using parameters for \code{html_document} from
# the YAML header parameters.
render("input.Rmd", "html_document")

# Render a single format, ignoring parameters for \code{html_document} in
# the YAML header. Any parameters not passed as arguments to
# \code{html_document()} will be assigned to their default values, regardless
# of anything in the YAML header
render("input.Rmd", html_document(toc = TRUE, toc_depth = 2))

# Render multiple formats
render("input.Rmd", c("html_document", "pdf_document"))
} # }

Arguments

Value

Details

R Markdown

See also

Examples