render
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.
Usage
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", "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 usingNULL
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 theoutput_dir
option allows for specifying the output file path as well, however, if also specifying the path, the directory must exist. Ifoutput_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 theoutput_file
value inI()
, 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 inoutput_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
ormathjax = "local"
). Note that this is only valid when the output format is read from metadata (i.e. not a custom format object passed tooutput_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. IfNULL
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 (seerun
). The default,auto
, allows theruntime
target specified in the YAML metadata to take precedence, and renders for astatic
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
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"))
# }