Download Rmd

# 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}
         %\VignetteEngine{knitr::rmarkdown}
         %\VignetteEncoding{UTF-8}
       ---

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.

    output:
      minidown::mini_document:
        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.

### Share

# 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,

    output:
      minidown::mini_document:
        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

Source

    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))
      file.size(temp_html)
    }

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

    knitr::kable(tibble::enframe(
      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↩︎