render {rmarkdown} | R Documentation

## Render R Markdown

### Description

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

### Usage

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

### Arguments

`input` | Input file (R script, Rmd, or plain markdown).
`output_format` | R Markdown output format to convert to. Pass `"all"` to render all formats defined within the file. Pass the name of a format (e.g. `"html_document"`) to render a single format or pass a vector of format names to render multiple formats. Alternatively you can pass an output format object; e.g. `html_document()`. If `NULL` is passed then the output format is the first one defined in the YAML metadata of the input file (defaulting to HTML if none is specified).
`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_file` | Output file. If `NULL` then a default based on the name of the input file is chosen.
`output_dir` | Output directory. An alternate directory to write the output file to (defaults to the directory of the input file).
`intermediates_dir` | Intermediate files directory. If `NULL`, intermediate files are written to the same directory as the input file; otherwise.
`knit_root_dir` | The working directory in which to knit the document; uses knitr's `root.dir` knit option. `NULL` means to follow the knitr default, which is to use the parent directory of the document.
`runtime` | The runtime target for rendering. `static` 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` | `TRUE` to clean intermediate files created during rendering.
`params` | 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` | (For expert use) Meta data 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` | Whether to run Pandoc to convert Markdown output.
`quiet` | `TRUE` to supress printing of the pandoc command line.
`encoding` | The encoding of the input file; see `file`.

### 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.

### 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()`).

### 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.

### See Also

knit, output_format, pandoc

### Examples

    ## Not run:

    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
    render("input.Rmd", "html_document")

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

    ## End(Not run)

[Package rmarkdown version 1.2 Index]