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

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

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