Writing Vignettes with the ‘minidown’ Package

The minidown::mini_document function provides simple and lightweight yet powerful HTML format. Even if all features are enabled, the size of document is comparable with the default html_vignette function.

How easy it is!

Only the difference is the YAML frontmatter.

3 steps to go

  1. Create an Rmd file under the vignettes directory

  2. Add a YAML front matter something like below

    title: "Writing Vignette with the 'minidown' Package"
    output: minidown::mini_document
    vignette: >
      %\VignetteIndexEntry{Writing Vignette with the 'minidown' Package}
  3. Write body

Configuring documents

The output format can be configured by the YAML front matter and by the _output.yml file. Most important things are minidown::mini_document in the output key, and %\VignetteEngine{knitr::rmarkdown} in the vignette key. These two declares the vignette to be rendered with minidown package.

The output format can be customized as usual in the R Markdown. Break lines, indent, and specify arguments like below. It is also possible to specify the arguments via vignettes/_output.yml. In that case, minidown::mini_document should be the top level key in the YAML file (cf. R Markdown: The Definitive Guide.

    framework: sakura
    theme: default
    toc: true
    toc_float: true
    toc_highlight: true
    code_folding: "hide"
    results_folding: "show"
    tabset: true
    code_download: true
    math: "katex"

Note that the framework and theme keys control appearance of the rendered document. The default framework is “sakura”, but there are some more like “water” and “spcss”. Each frameworks also have their own themes. For more details on options, visit https://minidown.atusy.net/. This page also provides examples of all the combinations of frameworks and themes.

The other contents of the YAML front matter are not minidown-specific.1.


Why authoring vignettes with the minidown package?

Because the minidown::mini_document function provides simple and lightweight yet powerful HTML format.

The rmarkdown package provides the html_vignette function as a lightweight format suitable for creating vignettes. As the document says, the html_vignette provides much lighter document than the html_document document. The html_vignette loses weight by omitting Bootstrap and jQuery from html_document, which in turn loses some nice appearance and features such as floating ToC and code folding. However, such features are very important for long format documents, i.e. vignettes.

The minidown::mini_document tries to provide as rich features as html_document. At the same time, it tries to be as light as html_vignette.

Rich opt-in features

Almost all features are opt-in in the minidown::mini_document function. Authors can chose which feature to add with a subtle weight via the YAML front matter. For example,

    toc: true
    toc_float: true
    toc_highlight: true
    code_folding: "hide"
    results_folding: "show"
    tabset: true
    code_download: true
    math: "katex"

For more details, refer a help document by ?minidown::mini_documewnt, or visit a document page which is a live example at the same time: https://minidown.atusy.net/.

Light weight

This section compares the size by compiling this document in variety of formats. There are two remarkable results.

  • The minidown::mini_document function can even be lighter than the html_vignette function when framework = "spcss" is chosen.
  • The minidown::mini_document with full features gains very small weights (< 20KB).
format size (KB)
html_vignette 23.601
mini_document(framework = “spcss”) 22.416
mini_document() # default 24.421
mini_document with full features 37.683
html_document 629.895
render_size <- function(output_format = rmarkdown::html_vignette()) {
  this_rmd <- knitr::current_input()
  temp_html <- tempfile(fileext = ".html")
  callr::r_safe(function(...) rmarkdown::render(...),
                args = list(input = this_rmd,
                            output_format = output_format,
                            output_file = temp_html,
                            params = list(eval_render = FALSE),
                            quiet = TRUE))

formats <- list(
  html_vignette = rmarkdown::html_vignette(),
  'mini_document(framework = "spcss")' = minidown::mini_document(framework = "spcss"),
  "mini_document() # default" = minidown::mini_document(),
  "mini_document with full features" = minidown::mini_document(
    toc = TRUE,
    toc_float = TRUE,
    toc_highlight = TRUE,
    code_folding = "hide",
    tabset = TRUE,
    code_download = TRUE,
    math = "katex_serverside"
  html_document = rmarkdown::html_document()

  purrr::map_dbl(formats, render_size) / 1000,
  name = "format",
  value = "size (KB)"

Note that if you are reading this vignette on CRAN, this page is the result of “mini_document with full features.” In that case, this page includes extra weight by providing download button which embeds source Rmd file (5.91KB).

  1. https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Writing-package-vignettes↩︎