vignettes/Writing-vignettes-with-minidown.Rmd
Writing-vignettes-with-minidown.RmdThe 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.
Only the difference is the YAML frontmatter.
Create an Rmd file under the vignettes directory
Add a YAML front matter something like below
Write body
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.
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.
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/.
This section compares the size by compiling this document in variety of formats. There are two remarkable results.
minidown::mini_document function can even be lighter than the html_vignette function when framework = "spcss" is chosen.minidown::mini_document with full features gains very small weights (< 20KB).| format | size (KB) |
|---|---|
| html_vignette | 23.600 |
| mini_document(framework = “spcss”) | 22.415 |
| mini_document() # default | 24.420 |
| mini_document with full features | 37.682 |
| html_document | 629.894 |
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).