Convert to an HTML document

Source: R/html_document.R

Format for converting from R Markdown to an HTML document.

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

toc

TRUE to include a table of contents in the output

toc_depth

Depth of headers to include in table of contents

toc_float

TRUE to float the table of contents to the left of the main document content. Rather than TRUE you may also pass a list of options that control the behavior of the floating table of contents. See the Floating Table of Contents section below for details.

number_sections

TRUE to number section headings

anchor_sections

TRUE to show section anchors when mouse hovers for all headers. A list can also be passed with style and/or depth to customize the behavior. See Anchor Sections Customization section.

section_divs

Wrap sections in <div> tags, and attach identifiers to the enclosing <div> rather than the header itself.

fig_width

Default width (in inches) for figures

fig_height

Default height (in inches) for figures

fig_retina

Scaling to perform for retina displays (defaults to 2, which currently works for all widely used retina displays). Set to NULL to prevent retina scaling. Note that this will always be NULL when keep_md is specified (this is because fig_retina relies on outputting HTML directly into the markdown document).

fig_caption

TRUE to render figures with captions

dev

Graphics device to use for figure output (defaults to png)

df_print

Method to be used for printing data frames. Valid values include "default", "kable", "tibble", and "paged". The "default" method uses a corresponding S3 method of print, typically print.data.frame. The "kable" method uses the knitr::kable function. The "tibble" method uses the tibble package to print a summary of the data frame. The "paged" method creates a paginated HTML table (note that this method is only valid for formats that produce HTML). In addition to the named methods you can also pass an arbitrary function to be used for printing data frames. You can disable the df_print behavior entirely by setting the option rmarkdown.df_print to FALSE. See Data frame printing section in bookdown book for examples.

code_folding

Enable document readers to toggle the display of R code chunks. Specify "none" to display all code chunks. Specify "hide" or "show" to hide or show all R code chunks by default, and let readers toggle the states on browsers. See the Code folding

code_download

Embed the Rmd source code within the document and provide a link that can be used by readers to download the code.

self_contained

Produce a standalone HTML file with no external dependencies, using data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. Note that even for self contained documents MathJax is still loaded externally (this is necessary because of its size).

theme

One of the following:

  • A bslib::bs_theme() object (or a list of bslib::bs_theme() argument values)

    • Use this option for custom themes using Bootstrap 4 or 3.

    • In this case, any .scss/.sass files provided to the css parameter may utilize the theme's underlying Sass utilities (e.g., variables, mixins, etc).

  • NULL for no theme (i.e., no html_dependency_bootstrap()).

  • A character string specifying a Bootswatch 3 theme name (for backwards-compatibility).

highlight

Syntax highlight engine and style. See the Highlighting section below for details.

"default" (and "textmate") will use highlightjs as syntax highlighting engine instead of Pandoc.

Any other value will be passed as Pandoc's highlighting style. Pandoc's built-in styles include "tango", "pygments", "kate", "monochrome", "espresso", "zenburn", "haddock" and "breezedark".

Two custom styles are also included, "arrow", an accessible color scheme, and "rstudio", which mimics the default IDE theme. Alternatively, supply a path to a .theme to use a custom Pandoc style. Note that custom theme requires Pandoc 2.0+.

Pass NULL to prevent syntax highlighting.

highlight_downlit

TRUE to use the downlit package as syntax highlight engine to highlight inline code and R code chunks (including providing hyperlinks to function documentation). The package needs to be installed to use this feature.

Only Pandoc color schemes are supported with this engine. With highlight = "default", it will use the accessible theme called "arrow". To learn more about downlit highlighting engine, see https://downlit.r-lib.org/.

math_method

Math rendering engine to use. This will define the math method to use with Pandoc.

  • It can be a string for the engine, one of "mathjax", "mathml", "webtex", "katex", "gladtex", or "r-katex" or "default" for mathjax.

  • It can be a list of

    • engine: one of "mathjax", "mathml", "webtex", "katex", or "gladtex".

    • url: A specific url to use with mathjax, katex or webtex. Note that for engine = "mathjax", url = "local" will use a local version of MathJax (which is copied into the output directory).

For example,

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

See Pandoc's Manual about Math in HTML for the details about Pandoc supported methods.

Using math_method = "r-katex" will opt-in server side rendering using KaTeX thanks to katex R package. This is useful compared to math_method = "katex" to have no JS dependency, only a CSS dependency for styling equation.

mathjax

Include mathjax. The "default" option uses an https URL from a MathJax CDN. The "local" option uses a local version of MathJax (which is copied into the output directory). You can pass an alternate URL or pass NULL to exclude MathJax entirely.

template

Pandoc template to use for rendering. Pass "default" to use the rmarkdown package default template; pass NULL to use pandoc's built-in template; pass a path to use a custom template that you've created. Note that if you don't use the "default" template then some features of html_document won't be available (see the Templates section below for more details).

extra_dependencies

Extra dependencies as a list of the html_dependency class objects typically generated by htmltools:htmlDependency().

css

CSS and/or Sass files to include. Files with an extension of .sass or .scss are compiled to CSS via sass::sass(). Also, if theme is a bslib::bs_theme() object, Sass code may reference the relevant Bootstrap Sass variables, functions, mixins, etc.

includes

Named list of additional content to include within the document (typically created using the includes function).

keep_md

Keep the markdown file generated by knitting.

lib_dir

Directory to copy dependent HTML libraries (e.g. jquery, bootstrap, etc.) into. By default this will be the name of the document with _files appended to it.

md_extensions

Markdown extensions to be added or removed from the default definition of R Markdown. See the rmarkdown_format for additional details.

pandoc_args

Additional command line options to pass to pandoc

...

Additional function arguments to pass to the base R Markdown HTML output formatter html_document_base

Value

R Markdown output format to pass to render

Details

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

R Markdown documents can have optional metadata that is used to generate a document header that includes the title, author, and date. For more details see the documentation on R Markdown metadata.

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

Highlighting

There are three highlighting engines available to HTML documents:

highlightjs

It does highlighting in the browser, using javascript It can only be used with the default template (i.e template = "default") and it has two styles ("default" and "textmate"). When activated, it adds two 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 could change 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 the Pandoc Manual). rmarkdown includes two custom themes to select with highlight parameter:

Custom themes are only available for Pandoc 2.0 and above.

downlit

downlit is an R package that provides a syntax highlighting engine in R. It will also do automatic linking of R code (requires internet connectivity). It is activated only if highlight_downlit = TRUE and only affects R code, leaving highlighting for other languages unchanged. The default color scheme is the accessible theme "arrow".

It requires some CSS in the template to correctly style links. This is included in the default template, but if you want to use with a custom template, you will need 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 a link symbol (🔗︎)

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

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

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

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

depth

Select the maximum header level to add the anchor link to. For example, this yaml will use the symbol style and only 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 of depth=6). You can also set anchors manually with depth = 0 using this syntax

# my header {.hasAnchor}

Using anchor sections will add some CSS to your document output for the styling, and a JS script if section_divs = TRUE. The anchor link itself is added using a Lua filter, and hence requires Pandoc 2.0+

Floating Table of Contents

You may specify a list of options for the toc_float parameter which control the behavior of the floating table of contents. Options include:

  • collapsed (defaults to TRUE) 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 to TRUE) controls whether page scrolls are animated when table of contents items are navigated to via mouse clicks.

  • print (defaults to TRUE) 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 the code_folding parameter. The state can be toggled individually on browsers. The document-wide toggle button is also provided for html_document and some of its extensions such as html_notebook. Note that this feature applies not only to source codes of chunks, but also markdown code blocks.

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

The default initial state of code folding respects the value given to the code_folding parameter. To override the behavior individually, add fold-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 class attribute to headers within a document. This will cause all sub-headers of the header with the .tabset attribute to appear within tabs rather than as standalone sections. For example:

## Quarterly Results {.tabset}

### By Product

### By Region

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

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

If tabbed sections relies on html_dependency_tabset(), for example by html_vignette(), these two attributes are not supported.

Templates

You can provide a custom HTML template to be used for rendering. The syntax for templates is described in the pandoc documentation. You can also use the basic pandoc template by passing template = NULL.

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

  • The theme parameter does not work (you can still provide styles using the css parameter).

  • For the highlight 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

  • The toc_float parameter will not work.

  • The code_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 if self_contained is TRUE (these two options can't be used together in normal pandoc templates).

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

Examples

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

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

render("input.Rmd", html_document(toc = TRUE))
} # }