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

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

`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`).
`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 of the pandoc command line.
`encoding` | The encoding of the input file. See `file` for more information.

### 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.12 Index]