Convert to an HTML notebook

Source: R/html_notebook.R

Format for converting from R Markdown to an HTML notebook.

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

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

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

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

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.

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

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

output_source

Define an output source for R chunks (ie, outputs to use instead of those produced by evaluating the underlying R code). See html_notebook_output for more details.

self_contained

Produce a standalone HTML file with no external dependencies. Defaults to TRUE. In notebooks, setting this to FALSE is not recommended, since the setting does not apply to embedded notebook output such as plots and HTML widgets.

...

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

Details

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