Movatterモバイル変換

Type:	Package
Title:	Dynamic Documents for R
Version:	2.30
Description:	Convert R Markdown documents into a variety of formats.
License:	GPL-3
URL:	https://github.com/rstudio/rmarkdown,https://pkgs.rstudio.com/rmarkdown/
BugReports:	https://github.com/rstudio/rmarkdown/issues
Depends:	R (≥ 3.0)
Imports:	bslib (≥ 0.2.5.1), evaluate (≥ 0.13), fontawesome (≥0.5.0), htmltools (≥ 0.5.1), jquerylib, jsonlite, knitr (≥1.43), methods, tinytex (≥ 0.31), tools, utils, xfun (≥0.36), yaml (≥ 2.1.19)
Suggests:	digest, dygraphs, fs, rsconnect, downlit (≥ 0.4.0), katex(≥ 1.4.0), sass (≥ 0.4.0), shiny (≥ 1.6.0), testthat (≥3.0.3), tibble, vctrs, cleanrmd, withr (≥ 2.4.2), xml2
VignetteBuilder:	knitr
Config/Needs/website:	rstudio/quillt, pkgdown
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
SystemRequirements:	pandoc (>= 1.14) - http://pandoc.org
NeedsCompilation:	no
Packaged:	2025-09-25 03:25:30 UTC; yihui
Author:	JJ Allaire [aut], Yihui Xie [aut, cre], Christophe Dervieux [aut], Jonathan McPherson [aut], Javier Luraschi [aut], Kevin Ushey [aut], Aron Atkins [aut], Hadley Wickham [aut], Joe Cheng [aut], Winston Chang [aut], Richard Iannone [aut], Andrew Dunning [ctb], Atsushi Yasumoto [ctb, cph] (cph: Number sections Lua filter), Barret Schloerke [ctb], Carson Sievert [ctb], Devon Ryan [ctb], Frederik Aust [ctb], Jeff Allen [ctb], JooYoung Seo [ctb], Malcolm Barrett [ctb], Rob Hyndman [ctb], Romain Lesur [ctb], Roy Storey [ctb], Ruben Arslan [ctb], Sergio Oller [ctb], Posit Software, PBC [cph, fnd], jQuery UI contributors [ctb, cph] (jQuery UI library; authors listed in inst/rmd/h/jqueryui/AUTHORS.txt), Mark Otto [ctb] (Bootstrap library), Jacob Thornton [ctb] (Bootstrap library), Bootstrap contributors [ctb] (Bootstrap library), Twitter, Inc [cph] (Bootstrap library), Alexander Farkas [ctb, cph] (html5shiv library), Scott Jehl [ctb, cph] (Respond.js library), Ivan Sagalaev [ctb, cph] (highlight.js library), Greg Franko [ctb, cph] (tocify library), John MacFarlane [ctb, cph] (Pandoc templates), Google, Inc. [ctb, cph] (ioslides library), Dave Raggett [ctb] (slidy library), W3C [cph] (slidy library), Dave Gandy [ctb, cph] (Font-Awesome), Ben Sperry [ctb] (Ionicons), Drifty [cph] (Ionicons), Aidan Lister [ctb, cph] (jQuery StickyTabs), Benct Philip Jonsson [ctb, cph] (pagebreak Lua filter), Albert Krewinkel [ctb, cph] (pagebreak Lua filter)
Maintainer:	Yihui Xie <xie@yihui.name>
Repository:	CRAN
Date/Publication:	2025-09-28 11:30:02 UTC

R Markdown Document Conversion

Description

Convert R Markdown documents into a variety of formats including HTML,MS Word, PDF, and Beamer.

Details

Thermarkdown package includes high level functions forconverting to a variety of formats. For example:

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

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

render("input.md", html_document())

Additional options can be specified along with the output format:

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

You can also include arbitrary pandoc command line arguments along with theother options:

render("input.Rmd", pdf_document(toc = TRUE, pandoc_args = "--listings"))

Author(s)

Maintainer: Yihui Xiexie@yihui.name (ORCID)

Authors:

• JJ Allairejj@posit.co

• Christophe Dervieuxcderv@posit.co (ORCID)

• Jonathan McPhersonjonathan@posit.co

• Javier Luraschi

• Kevin Usheykevin@posit.co

• Aron Atkinsaron@posit.co

• Hadley Wickhamhadley@posit.co

• Joe Chengjoe@posit.co

• Winston Changwinston@posit.co

• Richard Iannonerich@posit.co (ORCID)

Other contributors:

• Andrew Dunning (ORCID) [contributor]

• Atsushi Yasumoto (ORCID) (Number sections Lua filter) [contributor, copyright holder]

• Barret Schloerke [contributor]

• Carson Sievert (ORCID) [contributor]

• Devon Ryandpryan79@gmail.com (ORCID) [contributor]

• Frederik Austfrederik.aust@uni-koeln.de (ORCID) [contributor]

• Jeff Allenjeff@posit.co [contributor]

• JooYoung Seo (ORCID) [contributor]

• Malcolm Barrett [contributor]

• Rob HyndmanRob.Hyndman@monash.edu [contributor]

• Romain Lesur [contributor]

• Roy Storey [contributor]

• Ruben Arslanruben.arslan@uni-goettingen.de [contributor]

• Sergio Oller [contributor]

• Posit Software, PBC [copyright holder, funder]

• jQuery UI contributors (jQuery UI library; authors listed in inst/rmd/h/jqueryui/AUTHORS.txt) [contributor, copyright holder]

• Mark Otto (Bootstrap library) [contributor]

• Jacob Thornton (Bootstrap library) [contributor]

• Bootstrap contributors (Bootstrap library) [contributor]

• Twitter, Inc (Bootstrap library) [copyright holder]

• Alexander Farkas (html5shiv library) [contributor, copyright holder]

• Scott Jehl (Respond.js library) [contributor, copyright holder]

• Ivan Sagalaev (highlight.js library) [contributor, copyright holder]

• Greg Franko (tocify library) [contributor, copyright holder]

• John MacFarlane (Pandoc templates) [contributor, copyright holder]

• Google, Inc. (ioslides library) [contributor, copyright holder]

• Dave Raggett (slidy library) [contributor]

• W3C (slidy library) [copyright holder]

• Dave Gandy (Font-Awesome) [contributor, copyright holder]

• Ben Sperry (Ionicons) [contributor]

• Drifty (Ionicons) [copyright holder]

• Aidan Lister (jQuery StickyTabs) [contributor, copyright holder]

• Benct Philip Jonsson (pagebreak Lua filter) [contributor, copyright holder]

• Albert Krewinkel (pagebreak Lua filter) [contributor, copyright holder]

See Also

render,html_document,pdf_document,word_document,beamer_presentation

Determine all output formats for an R Markdown document

Description

Read the YAML metadata (and any common output YAML file) for thedocument and return the output formats that will be generated bya call torender.

Usage

all_output_formats(input, output_yaml = NULL)

Arguments

Details

This function is useful for front-end tools that require additionalknowledge of the output to be produced byrender (e.g. tocustomize the preview experience).

Value

A character vector with the names of all output formats.

List available R Markdown template in a package

Description

List the available template by name that can be used withdraft() to createa new document for R Markdown from a package.

Usage

available_templates(package = "rmarkdown", full_path = FALSE)

Arguments

Value

A character vector of templates name to use withindraft(). Iffull_path = TRUE, it returns the full path to the templates.

Examples

# List rmarkdown templates & create a draftavailable_templates()# List rticles templatesavailable_templates("rticles")

Convert to a Beamer presentation

Description

Format for converting from R Markdown to a Beamer presentation.

Usage

beamer_presentation(  toc = FALSE,  slide_level = NULL,  number_sections = FALSE,  incremental = FALSE,  fig_width = 10,  fig_height = 7,  fig_crop = "auto",  fig_caption = TRUE,  dev = "pdf",  df_print = "default",  theme = "default",  colortheme = "default",  fonttheme = "default",  highlight = "default",  template = "default",  keep_tex = FALSE,  keep_md = FALSE,  latex_engine = "pdflatex",  citation_package = c("default", "natbib", "biblatex"),  self_contained = TRUE,  includes = NULL,  md_extensions = NULL,  pandoc_args = NULL,  extra_dependencies = NULL)

Arguments

Details

See theonline documentationfor additional details on using thebeamer_presentation format.

Creating Beamer output from R Markdown requires that LaTeX be installed.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographies and Citationsarticle in the online documentation.

Value

R Markdown output format to pass torender()

Examples

## Not run: library(rmarkdown)# simple invocationrender("pres.Rmd", beamer_presentation())# specify an option for incremental renderingrender("pres.Rmd", beamer_presentation(incremental = TRUE))## End(Not run)

Compiling R scripts to a notebook

Description

R Markdown can also compile R scripts to a notebook which includescommentary, source code, and script output. Notebooks can be compiled to anyoutput format including HTML, PDF, and MS Word.

Overview

To compile a notebook from an R script you simply pass the script torender. For example:

rmarkdown::render("analysis.R")rmarkdown::render("analysis.R", "pdf_document")

The first call torender creates an HTML document, whereasthe second creates a PDF document.

By default the name of the script, username, and current date and time areincluded in the header of the generated notebook. You can override thisdefault behavior by including explicit metadata in a specially formatted Rcomment:

#' ---#' title: "Crop Analysis Q3 2013"#' author: "John Smith"#' date: "May 3rd, 2014"#' ---

Including Markdown

Note that the R comment used above to add a title, author, and dateincludes a single-quote as a special prefix character. This is aroxygen2 style comment, and it's actually possible to include manysuch comments in an R script, all of which will be converted to markdowncontent within the generated notebook. For example:

#' A script comment that includes **markdown** formatting.

Rather than displaying as an R comment in the compiled notebook anyroxygen2 style comment will be treated as markdown and renderedaccordingly.

knitr Spin

Including markdown within R comments is possible becauserendercalls theknitr spin function to convert the Rscript to an Rmd file. Thespin function also enables you to addknitrchunk options with another special comment prefix (#+).

Here's an example of a script that uses the various features ofspin:

https://github.com/yihui/knitr/blob/master/inst/examples/knitr-spin.R

For more details onknitr::spin see the following documentation:

https://yihui.org/knitr/demo/stitch/

Convert to a ConTeXt document

Description

Format for converting from R Markdown to PDF using ConTeXt.

Usage

context_document(  toc = FALSE,  toc_depth = 2,  number_sections = FALSE,  fig_width = 6.5,  fig_height = 4.5,  fig_crop = "auto",  fig_caption = TRUE,  dev = "pdf",  df_print = "default",  template = NULL,  keep_tex = FALSE,  keep_md = FALSE,  citation_package = c("default", "natbib", "biblatex"),  includes = NULL,  md_extensions = NULL,  output_extensions = NULL,  pandoc_args = NULL,  context_path = NULL,  context_args = NULL,  ext = c(".pdf", ".tex"))

Arguments

Details

ConTeXt needs to be installed, e.g., you can install it withtinytex::tlmgr_install("context").

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographiesand Citations article in the online documentation.

Value

R Markdown output format to pass torender.

Examples

## Not run: library(rmarkdown)# simple invocationrender("input.Rmd", context_document())## End(Not run)

Convert a Jupyter/IPython notebook to an R Markdown document

Description

Read a Jupyter/IPython notebook file (‘.ipynb’) viajsonlite::fromJSON(), convert its code cells to R Markdown codechunks, preserve Markdown cells, and write out the results to an Rmd file.

Usage

convert_ipynb(input, output = xfun::with_ext(input, "Rmd"))

Arguments

Details

This simple converter may have some rough edges, depending on how manyIPython-specific features are used in a notebook. For example, line magicsare not automatically converted (warnings will be issued if line magics aredetected), but you may consider using or writing R functions to replace themin R Markdown (e.g., the%load magic may be replaced byreticulate::source_python()). Cell magics will be converted to codechunks with the (knitr) language engine names being the magic names.For example, the cell magic%%js is converted to⁠```{js}⁠in R Markdown. This does not always work because not all IPython cell magicshave their counterparts inknitr's language engines, but common cellmagics like%%bash,%%sh,%%js,%%perl,%%python, and%%ruby should work.

Value

The output file path (invisibly).

Examples

# this is not a real ipynb file, but illustrates what convert_ipynb() doesnb_data <- list(  cells = list(    list(cell_type = 'markdown', source = 'Hi **Markdown**!'),    list(cell_type = 'code', source = 'print("Hi R Markdown!")')  ),  metadata = list(    kernelspec = list(language = 'python')  ))nb_file = tempfile(fileext = '.ipynb')jsonlite::write_json(nb_data, nb_file, auto_unbox = TRUE, pretty = TRUE)xfun::file_string(nb_file)  # show file content# convert to R Markdownnb_rmd = rmarkdown:::convert_ipynb(nb_file)xfun::file_string(nb_rmd)

Determine the default output format for an R Markdown document

Description

Read the YAML metadata (and any common output YAML file) for thedocument and return the output format that will be generated bya call torender.

Usage

default_output_format(input, output_yaml = NULL)

Arguments

Details

This function is useful for front-end tools that require additionalknowledge of the output to be produced byrender (e.g. tocustomize the preview experience).

Value

A named list with aname value containing the formatname and anoptions value that is a list containing all the optionsfor the format and their values. An option's default value will be returnedif the option isn't set explicitly in the document.

Create a new document based on a template

Description

Create (and optionally edit) a draft of an R Markdown document based on atemplate.

Usage

draft(file, template, package = NULL, create_dir = "default", edit = TRUE)

Arguments

Details

Thedraft function creates new R Markdown documents based ontemplates that are either located on the filesystem or within an R package.The template and its supporting files will be copied to the locationspecified byfile.

Value

The file name of the new document (invisibly).

Note

An R Markdown template consists of a directory that contains adescription of the template, a skeleton Rmd file used as the basis for newdocuments, and optionally additional supporting files that are providedalong with the skeleton (e.g. a logo graphic).

If the template directory is contained within a package then it should belocated atinst/rmarkdown/templates. For example, a package namedpubtools that wanted to provide a template namedquarterly_report would need to provide the following files withinthepubtools/inst/rmarkdown/templates directory:

quarterly_report/template.yaml
quarterly_report/skeleton/skeleton.Rmd

Thetemplate.yaml file should include aname field. If youwant to ensure that a new directory is always created for a given template,then you can add thecreate_dir field to thetemplate.yamlfile. For example:

create_dir: true

Theskeleton/skeleton.Rmd file should include the initial contentsyou want for files created from this template. Additional files can beadded to theskeleton directory, for example:

skeleton/logo.png

These files will automatically be copied to the directory containing thenew R Markdown draft.

Examples

## Not run: rmarkdown::draft("Q4Report.Rmd",                 template="/opt/rmd/templates/quarterly_report")rmarkdown::draft("Q4Report.Rmd",                 template="quarterly_report", package="pubtools")## End(Not run)

Find External Resource References

Description

Given an R Markdown document or HTML file, attempt to determine the set ofadditional files needed in order to render and display the document.

Usage

find_external_resources(input_file, encoding = "UTF-8")

Arguments

Details

This routine applies heuristics in order to scan a document forpossible resource references.

In R Markdown documents, it looks for references to files implicitlyreferenced in Markdown (e.g.![alt](img.png)), in the document'sYAML header, in raw HTML chunks, and as quoted strings in R code chunks(e.g.read.csv("data.csv")).

Resources specified explicitly in the YAML header for R Markdowndocuments are also returned. To specify resources in YAML, use theresource_files key:

---title: My Documentauthor: My Nameresource_files:  - data/mydata.csv  - images/figure.png---

Each item in theresource_files list can refer to:

1. A single file, such asimages/figure.png, or

2. A directory, such asresources/data, in which case all of thedirectory's content will be recursively included, or

3. A wildcard pattern, such asdata/*.csv, in which case all ofthe files matching the pattern will be included. No recursion is done inthis case.

In HTML files (and raw HTML chunks in R Markdown documents), this routinesearches for resources specified in common tag attributes, such as<img src="...">,<link href="...">, etc.

In all cases, only resources that exist on disk and are contained in thedocument's directory (or a child thereof) are returned.

Value

A data frame with the following columns:

path

The relative path from the document to the resource

explicit

Whether the resource was specified explicitly(TRUE) or discovered implicitly (FALSE)

web

Whether the resource is needed to display a Web page renderedfrom the document

Find thepandoc executable

Description

Searches for thepandoc executable in a few places and use thehighest version found, unless a specific version is requested.

Usage

find_pandoc(cache = TRUE, dir = NULL, version = NULL)

Arguments

Value

A list containing the directory and version of Pandoc (if found).

Note

Usually you do not need to install Pandoc if you use the RStudio IDE,because the IDE has bundled a version of Pandoc. If you have installed aversion of Pandoc by yourself and want to use this version instead, you mayuse thedir argument of this function.

Examples

rmarkdown::find_pandoc()rmarkdown::find_pandoc(dir = '~/Downloads/Pandoc')rmarkdown::find_pandoc(version = '2.7.3')

Convert to GitHub Flavored Markdown

Description

Format for converting from R Markdown to GitHub Flavored Markdown.

Usage

github_document(  toc = FALSE,  toc_depth = 3,  number_sections = FALSE,  math_method = "default",  preserve_yaml = FALSE,  fig_width = 7,  fig_height = 5,  dev = "png",  df_print = "default",  includes = NULL,  md_extensions = NULL,  hard_line_breaks = TRUE,  pandoc_args = NULL,  html_preview = TRUE,  keep_html = FALSE)

Arguments

Details

See theonline documentation for additional details on using thegithub_document()format.

Value

R Markdown output format to pass torender()

About Math support

Default behavior is to keep any inline equation using$ and any blockequation using⁠$$⁠ in the resulting markdown as Github will process thoseusing Mathjax.This feature is only available with Pandoc 2.10.1 and above

When using"webtex", PNG images with a white background are used by default sothat it shows correctly on Github on both light and dark theme. You canchoose to only output SVG for better quality by changing the URL used:

output:  github_document:    math_method:      engine: webtex      url: https://latex.codecogs.com/svg.image?

Background or fonts color cannot be changed for now and your equation may not be visible on dark theme.

Using"webtex" will be the default with Pandoc 2.0.4 until Pandoc 2.10. Before 2.0.4, Github document output does not support math.

Provide common HTML dependencies for R Markdown formats

Description

These functions provide common HTML dependencies (e.g. jquery, bootstrap)for re-use by other R Markdown formats.

Usage

html_dependency_jquery()html_dependency_jqueryui()html_dependency_bootstrap(theme)html_dependency_tocify()html_dependency_font_awesome()html_dependency_ionicons()html_dependency_pagedtable()html_dependency_highlightjs(highlight)html_dependency_tabset()html_dependency_codefolding_lua()

Arguments

Convert to an HTML document

Description

Format for converting from R Markdown to an HTML document.

Usage

html_document(  toc = FALSE,  toc_depth = 3,  toc_float = FALSE,  number_sections = FALSE,  anchor_sections = FALSE,  section_divs = TRUE,  fig_width = 7,  fig_height = 5,  fig_retina = 2,  fig_caption = TRUE,  dev = "png",  df_print = "default",  code_folding = c("none", "show", "hide"),  code_download = FALSE,  self_contained = TRUE,  theme = "default",  highlight = "default",  highlight_downlit = FALSE,  math_method = "default",  mathjax = "default",  template = "default",  extra_dependencies = NULL,  css = NULL,  includes = NULL,  keep_md = FALSE,  lib_dir = NULL,  md_extensions = NULL,  pandoc_args = NULL,  ...)

Arguments

output:  html_document:    math_method:      engine: katex      url: https://cdn.jsdelivr.net/npm/katex@0.11.1/dist

Details

See theonline documentation for additional details on using thehtml_documentformat.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographies and Citations article in the online documentation.

Value

R Markdown output format to pass torender

Highlighting

There are three highlighting engines available to HTML documents:

highlightjs

It does highlighting in the browser, using javascript Itcan only be used with the default template (i.etemplate = "default")and it has two styles ("default" and "textmate"). When activated, it addstwo additional dependencies to the output file: a JS script and a CSS file.For now, this is the default engine for the default template - this couldchange in the future.

Pandoc

Pandoc's built-in highlighting.engine works with any template,default or custom, and style can be chosen among the built-in ones ("tango","pygments", "kate", "monochrome", "espresso", "zenburn", "haddock" and"breezedark") or a path to a custom theme ".theme" file (see Details in thePandoc Manual).rmarkdown includes two custom themes to select withhighlightparameter:

• "arrow", an accessible style using colorsoptimized for accessibility and color contrast

• "rstudio", a color scheme close to RStudio's default highlighting andhighglightjs's textmate.

Custom themes are only available for Pandoc 2.0 and above.

downlit

downlit is an R package thatprovides a syntax highlighting engine in R. It will also do automaticlinking of R code (requires internet connectivity). It is activated only ifhighlight_downlit = TRUE and only affects R code, leavinghighlighting for other languages unchanged. The default color scheme isthe accessible theme "arrow".

It requires some CSS in the template to correctly style links. This is includedin the default template, but if you want to use with a custom template, you willneed to add this to your template:

$if(highlight-downlit)$<style type="text/css">  code a:any-link {   color: inherit; /* use colour from syntax highlighting */   text-decoration: underline;   text-decoration-color: #ccc;  }</style>$endif$

Anchor Sections Customization

This will be the default to activate anchor sections link on header

output:  html_document:    anchor_sections: TRUE

There are currently two options to modify the default behavior

style

Select a predefined visual style:

• style = "dash", the default, uses ‘⁠#⁠’, a minimalist choice that evokes the id selector from HTML and CSS.

• style = "symbol" will use alink symbol (🔗︎)

• style = "icon" will use an svg icon. ()

You can also customize using a css rule in yourdocument. For example, to get a pictogram (🔗):

a.anchor-section::before {  content: '\\01F517';}

About how to apply custom CSS in R Markdown document, seehttps://bookdown.org/yihui/rmarkdown-cookbook/html-css.html

depth

Select the maximum header level to add theanchor link to. For example, this yaml will use the symbol style andonly with level 1 and 2 headings:

output:  html_document:    anchor_sections:      style: icon      depth: 2

If omitted, anchor will be added to all headers (equivalent ofdepth=6). You can also set anchors manually withdepth = 0 using this syntax

# my header {.hasAnchor}

Using anchor sections will add some CSS to your document output for thestyling, and a JS script ifsection_divs = TRUE. The anchor link itselfis added using a Lua filter, and hence requires Pandoc 2.0+

Navigation Bars

If you have a set of html documents which you'd like to provide a commonglobal navigation bar for, you can include a "_navbar.yml" or "_navbar.html"file within the same directory as your html document and it will automaticallybe included at the top of the document.

The "_navbar.yml" file includestitle,type,left, andright fields (to define menu items for the left and right of the navbarrespectively). Menu items includetext andhref fields. For example:

title: "My Website"type: defaultleft:  - text: "Home"    href: index.html  - text: "Other"    href: other.htmlright:  - text: GitHub    href: https://github.com

Thetype field is optional and can take the value "default" or "inverse" (whichprovides a different color scheme for the navigation bar).

Alternatively, you can include a "_navbar.html" file which is a full HTML definitionof a bootstrap navigation bar. For a simple example of including a navigation bar seehttps://github.com/rstudio/rmarkdown-website/blob/master/_navbar.html.For additional documentation on creating Bootstrap navigation bars seehttps://getbootstrap.com/docs/4.5/components/navbar/.

Floating Table of Contents

You may specify a list of options for thetoc_float parameter whichcontrol the behavior of the floating table of contents. Options include:

• collapsed (defaults toTRUE) controls whether the table of contents appears with only the top-level (H2) headers. When collapsed the table of contents is automatically expanded inline when necessary.

• smooth_scroll (defaults toTRUE) controls whether page scrolls are animated when table of contents items are navigated to via mouse clicks.

• print (defaults toTRUE) controls whether the table of contents appears when user prints out the HTML page.

Code folding

Code blocks become foldable by specifying "show" or "hide" to thecode_folding parameter. The state can be toggled individually onbrowsers. The document-wide toggle button is also provided forhtml_document and some of its extensions such ashtml_notebook. Note that this feature applies not only to sourcecodes of chunks, but also markdown code blocks.

Supported languages are R, Python, Bash, SQL, C++, Stan, and Julia. Tosupport code blocks with other languages, addfoldable class to them(i.e.,class.source = "foldable" as a chunk option).

The default initial state of code folding respects the value given to thecode_folding parameter. To override the behavior individually, addfold-none to disable,fold-hide to initially hide,fold-show to initially show.

Tabbed Sections

You can organize content using tabs by applying the.tabset classattribute to headers within a document. This will cause all sub-headers ofthe header with the.tabset attribute to appear within tabs ratherthan as standalone sections. For example:

## Quarterly Results {.tabset}### By Product### By Region

Withhtml_document(), you can also specify two additional attributes tocontrol the appearance and behavior of the tabs. The.tabset-fadeattributes causes the tabs to fade in and out when switching. The.tabset-pills attribute causes the visual appearance of the tabs tobe "pill" rather than traditional tabs. For example:

## Quarterly Results {.tabset .tabset-fade .tabset-pills}

If tabbed sections relies onhtml_dependency_tabset(), for example byhtml_vignette(), these two attributes are not supported.

Templates

You can provide a custom HTML template to be used for rendering. The syntaxfor templates is described in thepandoc documentation. You can also usethe basic pandoc template by passingtemplate = NULL.

Note however that if you choose not to use the "default" HTML template thenseveral aspects of HTML document rendering will behave differently:

• Thetheme parameter does not work (you can still provide styles using thecss parameter).

• For thehighlight parameter, the default highlighting engine will resolve to Pandoc instead of highlightjs and highlighting style will default to "pygments". "textmate" style is not available as related to highlightjs

• Thetoc_float parameter will not work.

• Thecode_folding parameter will not work.

• Tabbed sections (as described above) will not work.

• Navigation bars (as described above) will not work.

• MathJax will not work ifself_contained isTRUE (these two options can't be used together in normal pandoc templates).

Due to the above restrictions, you might consider using theincludesparameter as an alternative to providing a fully custom template.

Examples

## Not run: library(rmarkdown)render("input.Rmd", html_document())render("input.Rmd", html_document(toc = TRUE))## End(Not run)

Base output format for HTML-based output formats

Description

Creates an HTML base output format suitable for passing as thebase_format argument of theoutput_format function.

Usage

html_document_base(  theme = NULL,  self_contained = TRUE,  lib_dir = NULL,  math_method = "default",  mathjax = "default",  pandoc_args = NULL,  template = "default",  dependency_resolver = NULL,  copy_resources = FALSE,  extra_dependencies = NULL,  css = NULL,  bootstrap_compatible = FALSE,  ...)

Arguments

output:  html_document:    math_method:      engine: katex      url: https://cdn.jsdelivr.net/npm/katex@0.11.1/dist

Value

HTML base output format.

Convert to an HTML fragment.

Description

An html fragment is suitable for inclusion into an external html page. Seehtml_document for full details - this is a minor variation thatassumes you will include the output into an existing document (e.g. a blogpost).

Usage

html_fragment(  number_sections = FALSE,  section_divs = TRUE,  fig_width = 7,  fig_height = 5,  fig_retina = 2,  fig_caption = TRUE,  dev = "png",  df_print = "default",  mathjax = TRUE,  includes = NULL,  keep_md = FALSE,  md_extensions = NULL,  pandoc_args = NULL,  ...)

Arguments

Details

See theonlinedocumentation for additional details on using thehtml_fragmentformat.

Value

R Markdown output format to pass torender

Convert to an HTML notebook

Description

Format for converting from R Markdown to an HTML notebook.

Usage

html_notebook(  toc = FALSE,  toc_depth = 3,  toc_float = FALSE,  number_sections = FALSE,  fig_width = 7,  fig_height = 5,  fig_retina = 2,  fig_caption = TRUE,  code_folding = "show",  theme = "default",  highlight = "textmate",  highlight_downlit = FALSE,  math_method = "default",  mathjax = "default",  extra_dependencies = NULL,  css = NULL,  includes = NULL,  md_extensions = NULL,  pandoc_args = NULL,  output_source = NULL,  self_contained = TRUE,  ...)

Arguments

output:  html_document:    math_method:      engine: katex      url: https://cdn.jsdelivr.net/npm/katex@0.11.1/dist

Details

See theonlinedocumentation for additional details on using thehtml_notebookformat.

Generate R Notebook Metadata

Description

A structured helper for the construction of metadata used by theR Notebook output functions. Seehtml_notebook_output formore details.

Usage

html_notebook_metadata(iframe = TRUE)

Arguments

Generate R Notebook Output

Description

Utilities for generating output for thehtml_notebook format,through theoutput_source function attached to aoutput_format.

Usage

html_notebook_output_html(html, meta = NULL)html_notebook_output_img(  path = NULL,  bytes = NULL,  attributes = NULL,  meta = NULL,  format = c("png", "jpeg"))html_notebook_output_png(  path = NULL,  bytes = NULL,  attributes = NULL,  meta = NULL,  format = c("png", "jpeg"))html_notebook_output_code(code, attributes = list(class = "r"), meta = NULL)

Arguments

Details

See theonlinedocumentation for additional details on using thehtml_notebookformat.

Convert to an HTML vignette

Description

A HTML vignette is a lightweight alternative tohtml_document()suitable for inclusion in packages to be released to CRAN. It reduces thesize of a basic vignette from 100k to around 10k.

Usage

html_vignette(  fig_width = 3,  fig_height = 3,  dev = "png",  df_print = "default",  css = NULL,  highlight = "pygments",  keep_md = FALSE,  readme = FALSE,  self_contained = TRUE,  tabset = FALSE,  code_folding = c("none", "show", "hide"),  extra_dependencies = NULL,  pandoc_args = NULL,  ...)

Arguments

Details

Compared tohtml_document(), it:

• never uses retina figures

• never uses a theme

• has a smaller default figure size

• uses a custom css stylesheet

See theonline documentationfor additional details on using thehtml_vignette() format.

Value

R Markdown output format to pass torender()

Tabbed Sections

You can organize content using tabs by applying the.tabset classattribute to headers within a document. This will cause all sub-headers ofthe header with the.tabset attribute to appear within tabs ratherthan as standalone sections. For example:

## Quarterly Results {.tabset}### By Product### By Region

Withhtml_document(), you can also specify two additional attributes tocontrol the appearance and behavior of the tabs. The.tabset-fadeattributes causes the tabs to fade in and out when switching. The.tabset-pills attribute causes the visual appearance of the tabs tobe "pill" rather than traditional tabs. For example:

## Quarterly Results {.tabset .tabset-fade .tabset-pills}

If tabbed sections relies onhtml_dependency_tabset(), for example byhtml_vignette(), these two attributes are not supported.

Code folding

Code blocks become foldable by specifying "show" or "hide" to thecode_folding parameter. The state can be toggled individually onbrowsers. The document-wide toggle button is also provided forhtml_document and some of its extensions such ashtml_notebook. Note that this feature applies not only to sourcecodes of chunks, but also markdown code blocks.

Supported languages are R, Python, Bash, SQL, C++, Stan, and Julia. Tosupport code blocks with other languages, addfoldable class to them(i.e.,class.source = "foldable" as a chunk option).

The default initial state of code folding respects the value given to thecode_folding parameter. To override the behavior individually, addfold-none to disable,fold-hide to initially hide,fold-show to initially show.

Include content within output

Description

Specify additional content to be included within an output document.

Usage

includes(in_header = NULL, before_body = NULL, after_body = NULL)includes_to_pandoc_args(includes, filter = identity)

Arguments

Details

Non-absolute paths for resources referenced from thein_header,before_body, andafter_bodyparameters are resolved relative to the directory of the input document.

Value

Includes list or pandoc args

Examples

## Not run: library(rmarkdown)html_document(includes = includes(before_body = "header.htm"))pdf_document(includes = includes(after_body = "footer.tex"))## End(Not run)

Convert to an ioslides Presentation

Description

Format for converting from R Markdown to anioslides presentation.

Usage

ioslides_presentation(  number_sections = FALSE,  logo = NULL,  slide_level = 2,  incremental = FALSE,  fig_width = 7.5,  fig_height = 4.5,  fig_retina = 2,  fig_caption = TRUE,  dev = "png",  df_print = "default",  smart = TRUE,  self_contained = TRUE,  widescreen = FALSE,  smaller = FALSE,  transition = "default",  math_method = "mathjax",  mathjax = "default",  analytics = NULL,  template = NULL,  css = NULL,  includes = NULL,  keep_md = FALSE,  lib_dir = NULL,  md_extensions = NULL,  pandoc_args = NULL,  extra_dependencies = NULL,  ...)

Arguments

output:  html_document:    math_method:      engine: katex      url: https://cdn.jsdelivr.net/npm/katex@0.11.1/dist

Details

See the online documentation for additional details on using theioslides_presentation format.

Note that, if abefore_body include is specified inincludes,then it will replace the standard title slide entirely.

Regarding previewing slide in RStudio IDE,ioslides_presentation() willalways open preview in a new Window and the RStudio IDE configuration "Open in ViewerPane" will have no effect for this format.

Value

R Markdown output format to pass torender().

Slide Basics

You can create a slide show broken up into sections by using the # and ##heading tags (you can also create a new slide without a header using ahorizontal rule (⁠----------⁠). For example here's a simple slide show:

---title: "Habits"author: John Doedate: March 22, 2005output: ioslides_presentation---# In the morning## Getting up- Turn off alarm- Get out of bed## Breakfast- Eat eggs- Drink coffee# In the evening## Dinner- Eat spaghetti- Drink wine----------![picture of spaghetti](images/spaghetti.jpg)## Going to sleep- Get in bed- Count sheep

You can add a subtitle to a slide or section by including text after thepipe (|) character. For example:

## Getting up | What I like to do first thing

Display Modes

The following single character keyboard shortcuts enable alternate displaymodes:

'f'

enable fullscreen mode

'w'

toggle widescreen mode

'o'

enable overview mode

'h'

enable code highlight mode

'p'

show presenter notes

PressingEsc exits all of these modes. See the sections below onCode Highlighting andPresenter Mode for additionaldetail on those modes.

Incremental Bullets

You can render bullets incrementally by adding theincrementaloption:

---output:  ioslides_presentation:    incremental: true---

If you want to render bullets incrementally for some slides but notothers you can use this syntax:

> - Eat eggs> - Drink coffee

Presentation Size

You can display the presentation using a wider form factor using thewidescreen option. You can specify that smaller text be used withthesmaller option. For example:

---output:  ioslides_presentation:    widescreen: true    smaller: true---

You can also enable thesmaller option on a slide-by-slide basisby adding the.smaller attribute to the slide header:

## Getting up {.smaller}

Adding a Logo

You can add a logo to the presentation using thelogo option (thelogo should be square and at least 128x128). For example:

---output:  ioslides_presentation:    logo: logo.png---

A 128x128 version of the logo graphic will be added to the title slide andan icon version of the logo will be included in the bottom-left footer ofeach slide.

Build Slides

Slides can also have a.build attribute that indicate that theircontent should be displayed incrementally. For example:

## Getting up {.build}

Slide attributes can be combined if you need to specify more than one,for example:

## Getting up {.smaller .build}

Code Highlighting

It's possible to select subsets of code for additional emphasis by adding aspecial "highlight" comment around the code. For example:

### <b>x <- 10y <- x * 2### </b>

The highlighted region will be displayed with a bold font. When you want tohelp the audience focus exclusively on the highlighted region press the'h' key and the rest of the code will fade away.

Tables

The ioslides template has an attractive default style for tables so youshouldn't hesitate to add tables for presenting more complex sets ofinformation. Pandoc markdown supports several syntaxes for definingtables which are described in thepandoc online documentation.

Advanced Layout

You can center content on a slide by adding the.flexboxand.vcenter attributes to the slide title. For example:

## Dinner {.flexbox .vcenter}

You can horizontally center content by enclosing it in adiv tagwith classcentered. For example:

<div>This text is centered.</div>

You can do a two-column layout using thecolumns-2 class.For example:

<div>  ![Image](image.png)  - Bullet 1  - Bullet 2  - Bullet 3</div>

Note that content will flow across the columns so if you want tohave an image on one side and text on the other you should makesure that the image has sufficient height to force the text tothe other side of the slide.

Text Color

You can color content using base color classes red, blue, green, yellow,and gray (or variations of them e.g. red2, red3, blue2, blue3, etc.).For example:

<div>This text is red</div>

Presenter Mode

A separate presenter window can also be opened (ideal for when you arepresenting on one screen but have another screen that's private to you).The window stays in sync with the main presentation window and alsoshows presenter notes and a thumbnail of the next slide. To enablepresenter mode add?presentme=true to the URL of the presentation,for example:

mypresentation.html?presentme=true

The presenter mode window will open and will always re-open with thepresentation until it's disabled with:

mypresentation.html?presentme=false

To add presenter notes to a slide you include it within a "notes"div. For example:

<div>This is my *note*.- It can contain markdown- like this list</div>

Printing and PDF Output

You can print an ioslides presentation from within browsers that havegood support for print CSS (i.e. as of this writing Google Chromehas the best support). Printing maintains most of the visual stylesof the HTML version of the presentation.

To create a PDF version of a presentation you can use Print to PDFfrom Google Chrome.

Run a shiny application asking for parameter configuration for the given document.

Description

Run a shiny application asking for parameter configuration for the given document.

Usage

knit_params_ask(  file = NULL,  input_lines = NULL,  params = NULL,  shiny_args = NULL,  save_caption = "Save",  encoding = "UTF-8")

Arguments

Value

named list with overridden parameter names and value.

Knitr options for an output format

Description

Define the knitr options for an R Markdown output format.

Usage

knitr_options(  opts_knit = NULL,  opts_chunk = NULL,  knit_hooks = NULL,  opts_hooks = NULL,  opts_template = NULL)

Arguments

Value

An list that can be passed as theknitr argumentof theoutput_format function.

See Also

output_format

Knitr options for an HTML output format

Description

Define knitr options for an R Markdown output format that createsHTML output.

Usage

knitr_options_html(fig_width, fig_height, fig_retina, keep_md, dev = "png")

Arguments

Value

An list that can be passed as theknitr argument of theoutput_format function.

See Also

knitr_options,output_format

Knitr options for a PDF output format

Description

Define knitr options for an R Markdown output formatthat creates PDF output.

Usage

knitr_options_pdf(fig_width, fig_height, fig_crop, dev = "pdf")

Arguments

Value

An list that can be passed as theknitr argument of theoutput_format function.

See Also

knitr_options,output_format

Provide common LaTeX dependencies

Description

These functions provide common LaTeX dependencies (e.g. tikz)for R Markdown formats that use LaTeX.

Usage

latex_dependency_tikz(libraries, options = NULL, extra_lines = NULL)

Arguments

Define a LaTeX package dependency

Description

Define a LaTeX package dependency

Usage

latex_dependency(name, options = NULL, extra_lines = NULL)

Arguments

Convert to a markdown document

Description

Format for converting from R Markdown to another variant of markdown (e.g.strict markdown or github flavored markdown)

Usage

md_document(  variant = "markdown_strict",  preserve_yaml = FALSE,  toc = FALSE,  toc_depth = 3,  number_sections = FALSE,  standalone = FALSE,  fig_width = 7,  fig_height = 5,  fig_retina = NULL,  dev = "png",  df_print = "default",  includes = NULL,  md_extensions = NULL,  pandoc_args = NULL,  ext = ".md")

Arguments

Details

See theonline documentationfor additional details on using themd_document() format.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

Value

R Markdown output format to pass torender()

Examples

## Not run: library(rmarkdown)render("input.Rmd", md_document())render("input.Rmd", md_document(variant = "markdown_github"))## End(Not run)

The YAML metadata of the current R Markdown document

Description

The objectmetadata stores the YAML metadata of the current R Markdowndocument as a list, which you may use in the R code chunks, e.g.rmarkdown::metadata$title (the title of the document),rmarkdown::metadata$author, andrmarkdown::metadata$foo (if youhave a YAML field namedfoo), etc.

Format

An object of classlist of length 0.

Examples

rmarkdown::metadata

Create a navbar HTML file from a navbar definition

Description

Create a navbar HTML file from a navbar definition

Usage

navbar_html(navbar)navbar_links_html(links)

Arguments

Value

Path to temporary file with navbar definition

Convert to an OpenDocument Text (ODT) document

Description

Format for converting from R Markdown to an ODT document.

Usage

odt_document(  number_sections = FALSE,  fig_width = 5,  fig_height = 4,  fig_caption = TRUE,  template = "default",  reference_odt = "default",  includes = NULL,  keep_md = FALSE,  md_extensions = NULL,  pandoc_args = NULL)

Arguments

Details

See theonlinedocumentation for additional details on using theodt_document format.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographiesand Citations article in the online documentation.

Value

R Markdown output format to pass torender

Examples

## Not run: library(rmarkdown)# simple invocationrender("input.Rmd", odt_document())# specify an option for syntax highlightingrender("input.Rmd", odt_document(highlight = "zenburn"))## End(Not run)

Define an R Markdown output format

Description

Define an R Markdown output format based on a combination of knitr and pandocoptions.

Usage

output_format(  knitr,  pandoc,  keep_md = FALSE,  clean_supporting = TRUE,  df_print = NULL,  pre_knit = NULL,  post_knit = NULL,  pre_processor = NULL,  intermediates_generator = NULL,  post_processor = NULL,  on_exit = NULL,  file_scope = NULL,  base_format = NULL)

Arguments

Value

An R Markdown output format definition that can be passed torender.

See Also

render,knitr_options,pandoc_options

Examples

## Not run: output_format(knitr = knitr_options(opts_chunk = list(dev = 'png')),              pandoc = pandoc_options(to = "html"))## End(Not run)

Define and merge an R Markdown's output format dependency

Description

Define and merge a dependency such as pre/post-processors from withinchunks. The merge happens explicitly when a list of dependencies arepassed toknitr::knit_meta_add() or implicitly when a dependencyisknitr::knit_printed. Defining a function that does the former isthe best way for package developers to share the dependency. On thecontrary, the latter is useful to declare a document-specific dependency.This function shares some arguments withoutput_format,but lacks the others because dependency is resolved afterpost_knitand beforepre_processor.

Usage

output_format_dependency(  name,  pandoc = list(),  pre_processor = NULL,  post_processor = NULL,  file_scope = NULL,  on_exit = NULL)

Arguments

Value

An list of arguments with the "rmd_dependency" class.

Examples

# Implicitly add lua filters from within a chunk# This relies on (implicit) printing of the dependency in a chunk via# knitr::knit_print()`output_format_dependency(  "lua_filter1",  pandoc = list(lua_filters = "example1.lua"))# Explicitly add lua filters from within a chunkknitr::knit_meta_add(list(output_format_dependency(  "lua_filter2",  pandoc = list(lua_filters = "example2.lua"))))# List the available dependencies# Note that the list may include dependencies with duplicated names. In that# case, the first one is merged to the output format and the others are# discarded.str(knitr::knit_meta("output_format_dependency", clean = FALSE))

The output metadata object

Description

This object provides a mechanism for users to attach metadata as an attribute(namedrmd_output_metadata) of the returned value ofrender(). The initial value of the metadata comes from in thermd_output_metadata field of the YAML frontmatter of an R Markdowndocument. The metadata can be queried via theoutput_metadata$get() method, and modified via theoutput_metadata$set() method.

Create a table in HTML with support for paging rows and columns

Description

Create a table in HTML with support for paging rows and columns

Usage

paged_table(x, options = NULL)

Arguments

Details

Below are the recognized table pagination options.

Note: There is a hard cap of 10,000 rows to ensure that pandoc will notfail when rendering the document.

Functions for generating pandoc command line arguments

Description

Functions that assist in creating various types of pandoc command linearguments (e.g. for templates, table of contents, highlighting, and contentincludes).

Usage

pandoc_variable_arg(name, value)pandoc_metadata_arg(name, value)pandoc_metadata_file_arg(file)pandoc_include_args(in_header = NULL, before_body = NULL, after_body = NULL)pandoc_highlight_args(highlight, default = "tango")pandoc_latex_engine_args(latex_engine)pandoc_toc_args(toc, toc_depth = 3)pandoc_citeproc_args()pandoc_lua_filter_args(lua_files)

Arguments

Details

Non-absolute paths for resources referenced from thein_header,before_body, andafter_bodyparameters are resolved relative to the directory of the input document.

Value

A character vector with pandoc command line arguments.

About Pandoc citeproc

For Pandoc version before 2.11, a pandoc filter ‘⁠pandoc-citeproc⁠’ isused. Since Pandoc 2.11, the feature is built-in and activated using‘⁠--citeproc⁠’ flag. ‘⁠pandoc_citeproc_arg⁠’ will return the correctswitches depending on the Pandoc version in use.

Examples

## Not run: library(rmarkdown)pandoc_include_args(before_body = "header.htm")pandoc_include_args(before_body = "header.tex")pandoc_highlight_args("kate")pandoc_latex_engine_args("pdflatex")pandoc_toc_args(toc = TRUE, toc_depth = 2)## End(Not run)

Check pandoc availability and version

Description

Determine whether pandoc is currently available on the system (optionallychecking for a specific version or greater). Determine the specific versionof pandoc available.

Usage

pandoc_available(version = NULL, error = FALSE)pandoc_version()

Arguments

Details

The system environment variable ‘⁠PATH⁠’ as well as the version of pandocshipped with RStudio (its location is set via the environment variable‘⁠RSTUDIO_PANDOC⁠’ by RStudio products like the RStudio IDE, RStudioServer, Shiny Server, and RStudio Connect, etc) are scanned for pandoc andthe highest version available is used. Please do not modify the environmentvariable ‘⁠RSTUDIO_PANDOC⁠’ unless you know what it means.

Value

pandoc_available returns a logical indicating whether therequired version of pandoc is available.pandoc_version returns anumeric_version with the version of pandoc found.

Examples

## Not run: library(rmarkdown)if (pandoc_available())  cat("pandoc", as.character(pandoc_version()), "is available!\n")if (pandoc_available("1.12.3"))  cat("required version of pandoc is available!\n")## End(Not run)

Convert a bibliograpy file

Description

Convert a bibliography file (e.g. a BibTeX file) to an R list, JSON text,or YAML text

Usage

pandoc_citeproc_convert(file, type = c("list", "json", "yaml"))

Arguments

Value

For 'type = "list"', and R list. For 'type = "json"' or 'type = "yaml"',a character vector with the specified format.

Convert a document with pandoc

Description

Convert documents to and from various formats using the pandoc utility.

Usage

pandoc_convert(  input,  to = NULL,  from = NULL,  output = NULL,  citeproc = FALSE,  options = NULL,  verbose = FALSE,  wd = NULL)

Arguments

Details

Supported input and output formats are described in thepandoc user guide.

The system path as well as the version of pandoc shipped with RStudio (ifrunning under RStudio) are scanned for pandoc and the highest versionavailable is used.

Examples

## Not run: library(rmarkdown)# convert markdown to various formatspandoc_convert("input.md", to = "html")pandoc_convert("input.md", to = "latex")# process citationspandoc_convert("input.md", to = "html", citeproc = TRUE)# add some pandoc optionspandoc_convert("input.md", to = "latex", options = c("--listings"))## End(Not run)

Get the path of the pandoc executable

Description

Returns the path of the pandoc executable used by functions in the thermarkdown package. This is the most recent version of pandoc found ineither the system path or shipped with RStudio.

Usage

pandoc_exec()

Details

See thepandoc manualfor pandoc commands.

Pandoc options for an output format

Description

Define the pandoc options for an R Markdown output format.

Usage

pandoc_options(  to,  from = rmarkdown_format(),  args = NULL,  keep_tex = FALSE,  latex_engine = c("pdflatex", "lualatex", "xelatex", "tectonic"),  ext = NULL,  lua_filters = NULL,  convert_fun = NULL)

Arguments

Details

Thefrom argument should be used very cautiously as it's important forusers to be able to rely on a stable definition of supported markdownextensions.

Value

An list that can be passed as thepandoc argument of theoutput_format function.

See Also

output_format,rmarkdown_format

Transform path for passing to pandoc

Description

Transform a path for passing to pandoc on the command line. Callspath.expand on all platforms. On Windows,transform it to a short path name if it contains spaces, and then convertforward slashes to back slashes (as required by pandoc for some pathreferences).

Usage

pandoc_path_arg(path, backslash = TRUE)

Arguments

Value

Transformed path that can be passed to pandoc on the command line.

Create a self-contained HTML document using pandoc.

Description

Create a self-contained HTML document by base64 encoding images,scripts, and stylesheets referred by the input document.

Usage

pandoc_self_contained_html(input, output)

Arguments

Value

(Invisibly) The path of the generated file.

Render a pandoc template.

Description

Use the pandoc templating engine to render a text file. Substitutions aredone using themetadata list passed to the function.

Usage

pandoc_template(metadata, template, output, verbose = FALSE)

Arguments

Value

(Invisibly) The path of the generated file.

Parse an HTML Notebook

Description

Parse an HTML notebook, retrieving annotation informationrelated to generated outputs in the document, as well as theoriginal R Markdown source document.

Usage

parse_html_notebook(path)

Arguments

Details

See theonlinedocumentation for additional details on using thehtml_notebookformat.

Convert to a PDF/LaTeX document

Description

Formats for converting from R Markdown to a PDF or LaTeX document.

Usage

pdf_document(  toc = FALSE,  toc_depth = 2,  number_sections = FALSE,  fig_width = 6.5,  fig_height = 4.5,  fig_crop = "auto",  fig_caption = TRUE,  dev = "pdf",  df_print = "default",  highlight = "default",  template = "default",  keep_tex = FALSE,  keep_md = FALSE,  latex_engine = "pdflatex",  citation_package = c("default", "natbib", "biblatex"),  includes = NULL,  md_extensions = NULL,  output_extensions = NULL,  pandoc_args = NULL,  extra_dependencies = NULL)latex_document(...)latex_fragment(...)

Arguments

Details

See theonlinedocumentation for additional details on using thepdf_documentformat.

Creating PDF output from R Markdown requires that LaTeX be installed.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographiesand Citations article in the online documentation.

Many aspects of the LaTeX template used to create PDF documents can becustomized using metadata. For example:

Available metadata variables include:

lang

Document language code (e.g. "es", "fr", "pt-BR")

fontsize

Font size (e.g. 10pt, 11pt, 12pt)

documentclass

LaTeX document class (e.g. article)

classoption

Option fordocumentclass (e.g. oneside); may be repeated

geometry

Options for geometry class (e.g. margin=1in); may be repeated

mainfont, sansfont, monofont, mathfont

Document fonts (works only with xelatex and lualatex, see thelatex_engine option)

linkcolor, urlcolor, citecolor

Color for internal, external, and citation links (red, green, magenta, cyan, blue, black)

linestretch

Options for line spacing (e.g. 1, 1.5, 3)

Value

R Markdown output format to pass torender

Examples

## Not run: library(rmarkdown)# simple invocationrender("input.Rmd", pdf_document())# specify an option for latex enginerender("input.Rmd", pdf_document(latex_engine = "lualatex"))# add a table of contents and pass an option to pandocrender("input.Rmd", pdf_document(toc = TRUE, "--listings"))## End(Not run)

Get the full paths of Lua filters in an R package

Description

Lua filters stored in a source package in the ‘inst/rmarkdown/lua’directory will be installed to the ‘rmarkdown/lua’ directory in thepackage path. This function finds the full paths of the Lua filters in theinstalled packages.

Usage

pkg_file_lua(filters = NULL, package = "rmarkdown")

Arguments

Value

A character vector of absolute file paths for the Lua filter from thepackage. The returned paths have been processed bypandoc_path_arg(), so they are ready to be used by Pandoc.

Examples

# list all Lua filters stored in the rmarkdown packagepkg_file_lua()# get a specific filterpkg_file_lua(c("pagebreak.lua", "latex_div.lua"))

Convert to a PowerPoint presentation

Description

Format for converting from R Markdown to a PowerPoint presentation. Pandocv2.0.5 or above is required.

Usage

powerpoint_presentation(  toc = FALSE,  toc_depth = 2,  number_sections = FALSE,  incremental = FALSE,  fig_width = 5,  fig_height = 4,  fig_caption = TRUE,  df_print = "default",  keep_md = FALSE,  md_extensions = NULL,  slide_level = NULL,  reference_doc = "default",  pandoc_args = NULL)

Arguments

Value

R Markdown output format to pass torender()

Publish an R Markdown Website

Description

Publish a website to RStudio Connect

Usage

publish_site(  site_dir = ".",  site_name = NULL,  method = c("rsconnect"),  server = NULL,  account = NULL,  render = TRUE,  launch_browser = interactive())

Arguments

Examples

## Not run: library(rmarkdown)publish_site()## End(Not run)

Relative path utility function

Description

Given a directory and a file, return a relative path from the directory tothe file, or the unmodified file path if the file does not appear to be inthe directory.

Usage

relative_to(dir, file)

Arguments

Value

Relative path from the directory to the file (or the unmodified filepath if the file does not appear to be in the directory).

Render R Markdown

Description

Render the input file to the specified output format using pandoc. If theinput requires knitting thenknit is called priorto 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", "shinyrmd", "shiny_prerendered"),  clean = TRUE,  params = NULL,  knit_meta = NULL,  envir = parent.frame(),  run_pandoc = TRUE,  quiet = FALSE,  encoding = "UTF-8")

Arguments

Details

Note that theknitrerror option is set toFALSE duringrendering (which is different from theknitr default value ofTRUE).

For additional details on rendering R scripts seeCompiling R scripts to a notebook.

If nooutput_format parameter is specified then the output format isread from the YAML front-matter of the input file. For example, thefollowing 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 nooutput_formatis passed torender 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 definedin another package (e.g.pkg::custom_format).

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

Value

Whenrun_pandoc = TRUE, the compiled document is written intothe output file, and the path of the output file is returned. Whenrun_pandoc = FALSE, the path of the Markdown output file, withattributesknit_meta (theknitr meta data collected from codechunks) andintermediates (the intermediate files/directoriesgenerated byrender()).

R Markdown

R Markdown supports all of the base pandoc markdown features as well as someoptional features for compatibility with GitHub Flavored Markdown (whichprevious versions of R Markdown were based on). Seermarkdown_format for details.

See Also

knit,output_format,https://pandoc.org

Examples

## Not run: library(rmarkdown)# Render the default (first) format defined in the filerender("input.Rmd")# Render all formats defined in the filerender("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 headerrender("input.Rmd", html_document(toc = TRUE, toc_depth = 2))# Render multiple formatsrender("input.Rmd", c("html_document", "pdf_document"))## End(Not run)

Delay Rendering for an Expression

Description

In a Shiny document, evaluate the given expression after the document hasfinished rendering, instead of during render.

Usage

render_delayed(expr)

Arguments

Details

This function is useful inside Shiny documents. It delays theevaluation of its argument until the document has finished its initialrender, so that the document can be viewed before the calculation isfinished.

Any expression that returns HTML can be wrapped inrender_delayed.

Value

An object representing the expression.

Note

expr is evaluated in acopy of the environment in whichtherender_delayed call appears. Consequently, no side effectscreated byexpr are visible in succeeding expressions, nor arechanges to the environment after the call torender_delayed visibletoexpr.

expr must be an expression that produces HTML.

Examples

## Not run: # Add the following code to an R Markdown documentdiv(Sys.time())render_delayed({ Sys.sleep(3)      # simulate an expensive computation div(Sys.time())})div(Sys.time())## End(Not run)

Render multiple documents as a website

Description

Render all of the R Markdown documents within a directory as a website.

Usage

render_site(  input = ".",  output_format = "all",  envir = parent.frame(),  quiet = FALSE,  encoding = "UTF-8")clean_site(input = ".", preview = TRUE, quiet = FALSE, encoding = "UTF-8")site_generator(input = ".", output_format = NULL)site_config(input = ".", encoding = "UTF-8")default_site_generator(input, output_format_filter = NULL, ...)

Arguments

Details

Therender_site function enables you to render a collection ofmarkdown documents within a directory as a website. There are tworequirements for a directory to be rendered as a website:

1. It must contain either an "index.Rmd" or "index.md" file.

2. It must contain a site configuration file ("_site.yml").

The most minimal valid website is an empty "index.Rmd" and an empty"_site.yml". With this configuration a single empty webpage would begenerated via a call torender_site. If you add additional markdowndocuments to the directory they will also be rendered. By default a site isrendered in the following fashion:

1. R Markdown (.Rmd) and plain markdown (.md) files in the rootdirectory are rendered. Note however that markdown files beginning with "_"are not rendered (this is a convention to designate files that are includedby top level documents).

2. All output and supporting files are copied to a "_site" subdirectoryof the website directory (this is configurable, see discussion below).

3. The following files arenot copied to the "_site"sub-directory:

   • Files beginning with "." (hidden files).

   • Files beginning with "_"

   • Files known to contain R source code (e.g. ".R", ".s", ".Rmd"), Rdata (e.g. ".RData", ".rds"), configuration data (e.g. ".Rproj","rsconnect") or package project management data (e.g."packrat", "renv").

   Note that you can override which files are included or excluded viasettings in "_site.yml" (described below).

4. Normally R Markdown renders documents as self-contained HTML.However,render_site ensures that dependencies (e.g. CSS,JavaScript, images, etc.) remain in external files. CSS/JavaScriptlibraries are copied to a "site_libs" sub-directory and plots/images arecopied to "_files" sub-directories.

You can remove the files generated byrender_site using theclean_site function.

Value

render_site returns the name of the site output file (relativeto the input directory).clean_site returns the names of thegenerated files removed during cleaning.site_config returns thecontents of _site.yml as an R list.default_site_generator returnsthe default site generator for R Markdown websites.

Configuration

A "_site.yml" file can be used to configure the behavior of site generation.Here is an example configuration file:

name: my-websiteoutput_dir: _siteinclude: ["demo.R"]exclude: ["docs.txt", "*.csv"]navbar:  title: "My Website"  left:    - text: "Home"      href: index.html    - text: "About"      href: about.htmloutput:  html_document:    toc: true    highlight: textmate

Thename field provides a suggested URL path for your website when itis published (by default this is just the name of the directory containingthe site). Theoutput_dir indicates which directory to copy sitecontent into ("_site" is the default if none is specified). Note that thiscan be "." to keep all content within the root website directory alongsidethe source code.

Theinclude andexclude fields enable you to override thedefault behavior vis-a-vis what files are copied into the "_site" directory(wildcards can be used as in the above example).

Thenavbar field can be used to define a navigation bar for websitesbased on thehtml_document format.

Finally, theoutput field enables you to specify output options thatare common to all documents within the website (you can also still providelocal options within each document that override any common options).

new_session: true causes each file to be rendered in a new R session.This prevents the masking problem that arises when different files usefunctions from different packages (namespaces) that share a common name, suchashere::here andlubridate::here ordplyr::filter andMASS::filter. The default behaviour ofrender_site is to use acommon R session.

autospin: true causes.R files to be spinned and rendered(as well as.Rmd files). Ifautospin is set to false (the default),.R files will not be spinned nor rendered.autospin can alsoenumerate a list of .R files to be spinned and rendered.

Custom Site Generation

The behavior of the default site generation function(rmarkdown::default_site) is described above. It is also possible todefine a custom site generator that has alternate behavior. A site generatoris an R function that is bound to by including it in the "site:" field of the"index.Rmd" or "index.md" file. For example:

title: "My Book"output: bookdown::gitbooksite: bookdown::bookdown_site

A site generation function should return a list with the following elements:

name:

The name for the website (e.g. the parent directoryname).

output_dir:

The directory where the website output is writtento. This path should be relative to the site directory (e.g. "." or"_site")

render:

An R function that can be called to generate thesite. The function should accept theinput_file,output_format,envir, andquiet arguments.

clean:

An R function that returns relative paths to the filesgenerated byrender_site (these files are the ones which will beremoved by theclean_site function.

subdirs(optional):

A logical flag that indicates ifthe generator supports nested source files in subdirectories of the project(TRUE) or only at the project root (FALSE). (e.g.blogdown:::blogdown_site())

Note that theinput_file argument will beNULL when the entiresite is being generated. It will be set to a specific file name if afront-end tool is attempting to preview it (e.g. RStudio IDE via the Knitbutton).

Whenquiet = FALSE therender function should also print a lineof output using themessage function indicating which outputfile should be previewed, for example:

if (!quiet)  message("\nOutput created: ", output)

Emitting this line enables front-ends like RStudio to determine which filethey should open to preview the website.

See the source code of thermarkdown::default_site function for aexample of a site generation function.

Render supporting files for an input document

Description

Render (copy) required supporting files for an input document to the_files directory that is associated with the document.

Usage

render_supporting_files(from, files_dir, rename_to = NULL)

Arguments

Value

The relative path to the supporting files. This path is suitablefor inclusion in HTMLhref andsrc attributes.

Resolve the output format for an R Markdown document

Description

Read the YAML metadata (and any common output YAML file) for thedocument and return an output format object that can bepassed to therender function.

Usage

resolve_output_format(  input,  output_format = NULL,  output_options = NULL,  output_yaml = NULL)

Arguments

Details

This function is useful for front-end tools that need to modifythe default behavior of an output format.

Value

An R Markdown output format definition that can be passed torender.

R Markdown input format definition

Description

Compose a pandoc markdown input definition for R Markdownthat can be passed as thefrom argument ofpandoc_options.

Usage

rmarkdown_format(extensions = NULL)from_rmarkdown(implicit_figures = TRUE, extensions = NULL)

Arguments

Details

By default R Markdown is defined as all pandoc markdown extensions withthe following tweaks for backward compatibility with the markdown package(+ features are added, - features are removed):

For more on pandoc markdown see thepandoc online documentation.

Value

Pandoc markdown format specification

See Also

output_format,pandoc_options

Examples

## Not run: rmarkdown_format("-implicit_figures")## End(Not run)

R Markdown Metadata

Description

Rmd files include a metadata section (typically located at the top of thefile) that can specify (among other things) the title, author, and date ofthe document. Metadata adheres to theYAML formatand is delimited by lines containing three dashes (---). Here is anexample metadata section:

---title: "Crop Analysis Q3 2013"author: Martha Smithdate: October 23rd, 2013---

Note that thetitle field is quoted. This is because titles oftencontained embedded colons (:) and colons followed by a space need tobe quoted in YAML.

Details

When title, author, and date metadata is provided it's used toautomatically create a title section within output documents. If you don'twant this section included in your document then you should remove thecorresponding metadata fields.

When generating PDF and Beamer output there are also a number of othermetadata fields that can be included to customize the appearance and themeof PDF output. For more details see the documentation forpdf_document andbeamer_presentation.

Convert to an RTF document

Description

Format for converting from R Markdown to an RTF document.

Usage

rtf_document(  toc = FALSE,  toc_depth = 3,  number_sections = FALSE,  fig_width = 5,  fig_height = 4,  keep_md = FALSE,  md_extensions = NULL,  pandoc_args = NULL)

Arguments

Details

See theonlinedocumentation for additional details on using thertf_document format.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographiesand Citations article in the online documentation.

Value

R Markdown output format to pass torender

Examples

## Not run: library(rmarkdown)# simple invocationrender("input.Rmd", rtf_document())# specify table of contents optionrender("input.Rmd", rtf_document(toc = TRUE))## End(Not run)

Run a Shiny document

Description

Start a Shiny server for the given document, and render it for display.

Usage

run(  file = "index.Rmd",  dir = dirname(file),  default_file = NULL,  auto_reload = TRUE,  shiny_args = NULL,  render_args = NULL)

Arguments

Details

Therun function runs a Shiny document by starting a Shinyserver associated with the document. Theshiny_args parameter can beused to configure the server; see therunAppdocumentation for details.

Once the server is started, the document will be rendered usingrender. The server will initiate a render of the documentwhenever necessary, so it is not necessary to callrun every timethe document changes: ifauto_reload isTRUE, saving thedocument will trigger a render. You can also manually trigger a render byreloading the document in a Web browser.

The server will render any R Markdown (.Rmd) document indir;thefile argument specifies only the initial document to berendered and viewed. You can therefore link to other documents in thedirectory using standard Markdown syntax, e.g.[Analysis Page 2](page2.Rmd).

Ifdefault_file is not specified, nor is a file specified on theURL, then the default document to serve at/ is chosen from (inorder of preference):

• Ifdir contains only oneRmd, thatRmd.

• The file ‘index.Rmd’, if it exists indir.

• The firstRmd that hasruntime: shiny in its YAML metadata.

• The file ‘index.html’ (or ‘index.htm’), if it exists indir.

If you wish to share R code between your documents, place it in a filenamedglobal.R indir; it will be sourced into the globalenvironment.

Value

Invisible NULL.

Note

Unlikerender,run does not render the document toa file on disk. In most cases a Web browser will be started automaticallyto view the document; seelaunch.browser in therunApp documentation for details.

When using an external web browser with the server, specify the name of theR Markdown file to view in the URL (e.g.http://127.0.0.1:1234/foo.Rmd). A URL without a filename will showthedefault_file as described above.

Examples

## Not run: # Run the Shiny document "index.Rmd" in the current directoryrmarkdown::run()# Run the Shiny document "shiny_doc.Rmd" on port 8241rmarkdown::run("shiny_doc.Rmd", shiny_args = list(port = 8241))## End(Not run)

Add code to a shiny_prerendered context

Description

Programmatic equivalent to including a code chunk with acontext in a runtime: shiny_prerendered document.

Usage

shiny_prerendered_chunk(context, code, singleton = FALSE)

Arguments

Clean prerendered content for the specified Rmd input file

Description

Remove the associated html file and supporting _files directoryfor a shiny_prerendered documet.

Usage

shiny_prerendered_clean(input)

Arguments

Get the server startup code for a shiny_prerendered server instance

Description

Get the server startup code for a shiny_prerendered server instance

Usage

shiny_prerendered_server_start_code(server_envir)

Arguments

Determine website resource files for a directory

Description

Determine which files within a given directory should be copied inorder to serve a website from the directory. Attempts to automaticallyexclude source, data, hidden, and other files not required to servewebsite content.

Usage

site_resources(site_dir, include = NULL, exclude = NULL, recursive = FALSE)

Arguments

Value

Character vector of files and directories to copy

Convert to a slidy presentation

Description

Format for converting from R Markdown to a slidy presentation.

Usage

slidy_presentation(  number_sections = FALSE,  incremental = FALSE,  slide_level = NULL,  duration = NULL,  footer = NULL,  font_adjustment = 0,  fig_width = 8,  fig_height = 6,  fig_retina = 2,  fig_caption = TRUE,  dev = "png",  df_print = "default",  self_contained = TRUE,  highlight = "default",  math_method = "default",  mathjax = "default",  template = "default",  css = NULL,  includes = NULL,  keep_md = FALSE,  lib_dir = NULL,  md_extensions = NULL,  pandoc_args = NULL,  extra_dependencies = NULL,  ...)

Arguments

output:  html_document:    math_method:      engine: katex      url: https://cdn.jsdelivr.net/npm/katex@0.11.1/dist

Details

See theonlinedocumentation for additional details on using theslidy_presentationformat.

For more information on markdown syntax for presentations see thepandoc online documentation.

Value

R Markdown output format to pass torender

Examples

## Not run: library(rmarkdown)# simple invocationrender("pres.Rmd", slidy_presentation())# specify an option for incremental renderingrender("pres.Rmd", slidy_presentation(incremental = TRUE))## End(Not run)

Convert to an MS Word document

Description

Format for converting from R Markdown to an MS Word document.

Usage

word_document(  toc = FALSE,  toc_depth = 3,  number_sections = FALSE,  fig_width = 5,  fig_height = 4,  fig_caption = TRUE,  df_print = "default",  highlight = "default",  reference_docx = "default",  keep_md = FALSE,  md_extensions = NULL,  pandoc_args = NULL)

Arguments

Details

See theonlinedocumentation for additional details on using theword_document format.

R Markdown documents can have optional metadata that is used to generate adocument header that includes the title, author, and date. For more detailssee the documentation on R Markdownmetadata.

R Markdown documents also support citations. You can find more information onthe markdown syntax for citations in theBibliographiesand Citations article in the online documentation.

Value

R Markdown output format to pass torender

Examples

## Not run: library(rmarkdown)# simple invocationrender("input.Rmd", word_document())# specify an option for syntax highlightingrender("input.Rmd", word_document(highlight = "zenburn"))## End(Not run)

Parse the YAML front matter from a file

Description

Parse the YAML front matter from a file

Usage

yaml_front_matter(input, encoding = "UTF-8")

Arguments