html_vignette: Convert to an HTML vignette

Description

A HTML vignette is a lightweight alternative to html_document() suitable for inclusion in packages to be released to CRAN. It reduces the size 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,
  ...
)

Value

R Markdown output format to pass to render()

Arguments

fig_width: Default width (in inches) for figures
fig_height: Default height (in inches) for figures
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.
css: One or more css files to include.
highlight, ...: Additional arguments passed to html_document(). Please note that theme and fig_retina are hard-coded. Setting any of those will yield an error.
keep_md: Keep the markdown file generated by knitting.
readme: Use this vignette as the package README.md file (i.e. render it as README.md to the package root). Note that if there are image files within your vignette you should be sure to add README_files to .Rbuildignore.
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).
tabset: Opt-in tabbed-sections feature inspired by html_document(). See section "Tabbed Sections" for the detail. This feature also allows navigation to the tab from table of contents and URL.
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
extra_dependencies: Extra dependencies as a list of the html_dependency class objects typically generated by htmltools:htmlDependency().
pandoc_args: Additional command line options to pass to pandoc

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.

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.

Details

Compared to html_document(), it:

never uses retina figures
never uses a theme
has a smaller default figure size
uses a custom css stylesheet

See the online documentation for additional details on using the html_vignette() format.