minidown::mini_document

Atsushi Yasumoto

2022-02-13

Manual Download Rmd

This article introduces rich features of minidown::mini_document with live examples. This format is powered by R Markdown, Pandoc, KaTeX and light weight CSS framewroks such as sakura (default), Water.css, mini.css, and so on.

If you haven’t installed the minidown package on R, install it by

remotes::install_github('atusy/minidown')

Documentation is ready at here.

1 Frameworks and themes

THe default framework and its theme are "sakura" and "default". Followings are the list of available ones. To preview them, use the UI at the top of this page.

framework theme
sakura default, dark_solarized, dark, earthly, ink, vader
spcss spcss
water light, dark
mini default, nord, dark
none none

Here’s an example YAML frontmatter specifying a framework and a theme.

output:
  minidown::mini_document:
    framework: sakura
    theme: default

2 Code folding

Code folding can be controlled by the YAML frontmatter like:

output:
  minidown::mini_document:
    code_folding:
      source: show
      output: show
      message: hide
      warning: hide
      error: show

The above results in

Source 
f <- function() {
  print(1)
  message('message')
  warning('warning')
  stop('error')
}
f()
Output 
## [1] 1
Message 
## message
Warning 
## Warning in f(): warning
Error 
## Error in f(): error

If the code folding is specified for some of them, then the code folding of the others will be none.

Like rmarkdown::html_document, code_folding: show indicates source is show and others are none.

By default code_folding is none, however, you can select some chunks be folded by giving the details class (e.g., class.source='details').

2.1 Show/hide exceptions

When source: show, all the sources are shown. In case you need exceptions, add the hide class to the source. If you want to hide all with exceptions, add the show class to the exceptions. Of course, this feature is not limited to the source.

---
output:
  minidown::mini_document:
    code_folding:
      source: show
---

```{r}
'This is shown'
```


```{r, class.source='hide'}
'This is hidden'
```

and hide classes.

2.2 Change summary

The content of summary can be controlled via summary.* chunk options. This feature is useful when you want to show the title of the source, to treat the output as a hidden answer, and so on.

iris.R 
# summary.source='iris.R', summary.output='Answer', class.output='hide'
head(iris)
Answer 
##   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1          5.1         3.5          1.4         0.2  setosa
## 2          4.9         3.0          1.4         0.2  setosa
## 3          4.7         3.2          1.3         0.2  setosa
## 4          4.6         3.1          1.5         0.2  setosa
## 5          5.0         3.6          1.4         0.2  setosa
## 6          5.4         3.9          1.7         0.4  setosa

2.3 Fold only some

Even if none is specified in YAML, code folding can be enabled for selected chunks by adding the details class.

---
output:
  minidown::mini_document:
    code_folding: none
---

```{r}
'This is shown'
```


```{r, class.source='details hide'}
'This is hidden'
```

2.4 Prefer rmarkdown::html_document

If you prefer rmarkdown::html_document except for the code foliding, specify the framework: bootstrap.

output:
  minidown::mini_document:
    framework: bootstrap
    code_folding: show

3 Results folding

By specifying result_folding: show or hide, you can fold entire results.

output:
  minidown::mini_document:
    results_folding: show # hide or none

This is a good option when you have side effects such as drawing figures and tables. Result button is placed on the left so that you can distinguish from code_folding buttons.

Source 
knitr::kable(iris[1:2, ])
Results
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa

3.1 Change summary text

By default, summary text is “Results”. You can change this by a chunk option, summary.results. Just like summary.* in code folding.

3.2 Multiple results per chunk

If you have multiple results per chunk and combine them to a single folding, you have three options.

3.2.1 Set chunk options

with results='hold' and/or fig.show='hold'.

Source 
'foo'
knitr::kable(iris[1:2, ])
Results
Output 
## [1] "foo"
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa

3.2.2 Iterate with for or lapply

or their friends.

Source 
for (i in 1:2) print(i)
Results
Output 
## [1] 1
## [1] 2

3.2.3 Define a function with side effects

Source 
f <- function() {
  print('foo')
  knitr::knit_print(knitr::kable(iris[1:2, ]))
}

f()
Results
Output 
## [1] "foo"
Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa

3.3 Exceptionally show/hide some results

To disable folding for some chunks, specify results.folding=NULL as a chunk option. When results_folding: show and you want to hide for some, then specify results.folding='hide' as a chunk option. Similarly, you make exeptions for results_folding: hide as well.

To disable folding by default, but enable it for some chunks, then specify results_folding: show # or hide as a YAML front matter, and run knitr::opts_chunk$set(results.folding=NULL) at the beggining of your document. Then, you can enable the feature for selected chunks by specifying 'show' or 'hide' to the results.folding chunk option.

---
output:
  minidown::mini_document:
    result_folding: show
---

```{r, include=FALSE}
knitr::opts_knit$set(results.folding=NULL)
```

```{r}
'This chunk does not fold results'
```


```{r, results.folding='hide'}
'This chunk hides not fold results'
```

4 Floating TOC

Table of contents can be floated on the left of the page by specifying toc_float: true. The layout is responsive to the windows size. Thus, floating TOC is available when the viewport has the enough width. See what happens by shrinking the width of your browser. Also, the floating ToC can also be highlighted according to the browsing section by specifying toc_highlight: true

output:
  minidown::mini_document:
    toc: true
    toc_float: true
    toc_highlight: true

5 Tabset

5.1 Introduction

Sections become tabs when they belong to the tabset-class section, and minidown::mini_document(tabset = TRUE). This feature is similar to the one in rmarkdown::html_document. Two major difference are

  • The table of contents can navigate to a specific tab.
  • Each tabs have unique URLs which can be shared with others.

2 + 1 steps to use:

  1. Add the tabset class to a header (e.g., # Tabset {.tabset})
  2. Nest headers with some contents (e.g., ## Introduction and ## Example Rmd)
  3. Optionally, control initially active tab by adding the active class to a nested header (e.g., ## Example Rmd {.active})

Note that a tab may nest tabs, however there will be

  • A conflict with the navigation to tabs from URL or ToC.
  • A conflict with the toc_highlight option (cf. Floating TOC).

5.2 Example Rmd

---
title: tabset
output:
  minidown::mini_document:
    tabset: true
---

# Tabset {.tabset}

## Tab 1

This is the first tab.

## Tab 2 {.active}

This is the second tab, which is initially active due to the `{.active}` attribute.
If the attribute is missing, the first tab is initially active.

6 Tooltips

Tooltips are available.

[text]{tooltip='tooltip'}

7 Math with KaTeX

$\sum_{i=1}^{10}{\alpha_i}$ becomes ∑i=110αi\sum_{i=1}^{10}{\alpha_i} and

$$
\sum_{i=1}^{10}{\alpha_i}
$$

becomes

∑i=110αi \sum_{i=1}^{10}{\alpha_i}

8 Appendix: markdown results

8.1 Headings (H2)

8.1.1 H3

8.1.1.1 H4

8.1.1.1.1 H5
8.1.1.1.1.1 H6

8.2 Block quotations

Single

Nesting

another

8.3 Code blocks

A code block without line numbers.

Code block

A code block with line numbers.

f <- function() {
  print(1)
  message('message')
  warning('warning')
  stop('error')
}
f()

8.3.1 Code blocks with long lines

8.3.1.1 Without specifiying language

long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long

8.3.1.2 With specifying language

8.3.1.2.1 Without line numbers
long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long
8.3.1.2.2 With line numbers
long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long long

8.4 Lists

8.4.1 Bullet lists

Tight

  • Tight 1
  • Tight 2
    • Tight 2-1
    • Tight 2-2

Loose

  • Loose 1

  • Loose 2

  • Loose 3

8.4.2 Ordered lists

  1. one
  2. two
  3. three

8.4.3 Task lists

  • an unchecked task list item
  • checked item

8.4.4 Definition lists

Term 1
Definition 1
Term 2
Definition 2a
Definition 2b

8.5 Horizontal rule

8.6 Table

Sepal.Length Sepal.Width Petal.Length Petal.Width Species
5.1 3.5 1.4 0.2 setosa
4.9 3.0 1.4 0.2 setosa
4.7 3.2 1.3 0.2 setosa
4.6 3.1 1.5 0.2 setosa
5.0 3.6 1.4 0.2 setosa
5.4 3.9 1.7 0.4 setosa

8.7 Inline formatting

  • Emphasis
  • Strong emphasis
  • Strikeout
  • superscript
  • subscript
  • Verbatim
  • Small caps

8.9 Image

Atusy’s avator

8.10 Footnote

See1

  1. footnote↩︎