How easy it is!
Only the difference is the YAML frontmatter.
3 steps to go
Create an Rmd
file under the vignettes
directory
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}
---
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..
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).
html_vignette |
24.003 |
mini_document(framework = “spcss”) |
23.952 |
mini_document() # default |
25.957 |
mini_document with full features |
39.462 |
html_document |
630.237 |
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).