3 Worked examples for Quarto and booktem features

As you work on your own book, you might find the following features useful for inspiration.

3.1 Quarto guide

To check different features of Quarto, you can see an extensive user guide online.

3.2 Worked examples

If you look through these books for inspiration, you can check the code to see how they do it.

Dr Wil Toivo and I are rewriting the Fundamentals of Quantitative Analysis book and you can see our github repository.

You can also see the Applied Data Skills book developed by Dr Emily Nordmann and Prof Lisa DeBruine, along with their github repository.

3.3 Useful features

3.3.1 Markdown

Quarto still uses Markdown for formatting, so you can see this part of the Quarto guide for Markdown Basics.

3.3.1.1 Headers

The book template table of contents goes by default to level 3 headers (but you can go to level 6 headers if you really want), so keep in mind what will be a logical nesting of headers, sub-headers etc. You add a hash for each level of header:

# Level 1 header

## Level 2 header

### Level 3 header

3.3.1.1.1 Header extra formatting

If you want to get super fancy Dr Gaby Mahrholz worked this out for how to change the colour of headers. You can essentially add css code to add extra formatting. For example, to create this orange header above, you add css code in curly brackets:

##### [Header extra formatting]{style="color: #EBA347; text-transform: uppercase;"}

3.3.1.2 Text formatting

You make text italics by surrounding it with one star (*italics*), or bold by surrounding it with two stars (**bold**).

If you want to give text code formatting, you can add back ticks around it.

`example code`

produces:

example code.

If you want to add bullet points, you can use - or *:

- Bullet point 1

- Bullet point 2

- Bullet point 3

Bullet point 1
Bullet point 2
Bullet point 3

The same applies to numbered lists:

1. List 1

2. List 2

3. List 3

List 1
List 2
List 3

Or even sub-lists with a little indent:

1. List 1

    1. Sublist 1
    
    2. Sublist 2

2. List 2

List 1
1. Sublist 1
2. Sublist 2
List 2

3.3.1.3 Links

You can add hyperlinks with the form:

[hyperlinks](https://quarto.org/docs/authoring/markdown-basics.html#links-images)

where the writing in square brackets is the text, and the link goes in the round brackets. By default, these link within the current page which I find infuriating. So, you can add a little html code to open a new tab with the link:

[hyperlinks](https://quarto.org/docs/authoring/markdown-basics.html#links-images){target="_blank"}

3.3.1.4 Internal hyperlinks

If you want to reference a chapter or section of your book, you can create internal hyperlinks through curly brackets and a hash. For example, if I wanted to point you back to the Workshop Plan chapter, you first need to add a tag on the chapter heading:

# Workshop plan {#workshop_plan}

You can then use the tag to create a link with a similar format to URL hyperlinks:

...back to the [Workshop Plan](#workshop_plan) chapter

3.3.1.5 Images

There are different ways to add images, where the Markdown version uses a similar format to links which I will demonstrate through this duck:

![This is a duck.](images/Duck.png)

This is a duck. If Helena is reading this, yes it has a creative commons licence.

There are some cool new Quarto features making it easy to combine multiple images. For example, we can add two ducks and specify we want them in two columns.

::: {#fig-duck layout-ncol=2}
![](images/images/Duck.png)
![](images/images/Duck.png)
Duck 1 (left) and Duck 2 (right). 
:::

Figure 3.1: Duck 1 (left) and Duck 2 (right).

You can also reference figures to add little hyperlinks and automatically number them. The title after the hash must start with fig to be registered as a figure, and you can also add tbl to number tables separately.

Figure 3.1 showed two ducks side by side. You do not even need to type Figure: @fig-duck.

You can also use knitr to add figures, and using code chunks has some new handy features using tags. They work in a similar way to code options, but make it easier to add longer captions etc, as shown in Figure 3.2.

```{r}
#| label: fig-img-duck
#| fig.cap: "This is a longer caption about our beloved duck."
#| fig-alt: "You can also add alt text to images."

knitr::include_graphics("images/Duck.png")
```

You can also add alt text to images. — Figure 3.2: This is a longer caption about our beloved duck.

3.3.2 Code chunks

If you are making a book to show code, there are a couple of features that might be useful.

Adding code chunks will by default show both the code and output:

```{r}
rnorm(n = 5, mean = 10, sd = 2)
```

rnorm(n = 5, mean = 10, sd = 2)

[1]  8.705339  8.960337 10.406693 10.068577 10.987172

There are several features you can edit by adding different options. For example, if you do not want to show the code, you can set echo=FALSE after the r {r echo=FALSE}:

[1] 11.97414 11.24457 10.43147 11.49562 11.02486

If you want to demonstrate code but not execute it - such as to demonstrate inaccurate code, you can set eval=FALSE after the r {r eval=FALSE}:

rnorm(n = 5, mean = 10, sd = 2)

I spent maybe an hour disappearing into a rabbit hole to find an elegant way of allowing people to copy and paste a whole code chunk - chunk code and all - that you might find it useful. The solution was on this R Markdown Cookbook by Xie et al. for verbatim code chunks. Essentially, I wanted to make it easy for students to copy and paste code chunks I give them, to make it easier to create problem solving activities.

You need to wrap your text/code/code chunks in a markdown verbatim chunk which produces this:


`r city` is a city in Scotland. 

```{r}
city <- "Glasgow"
```

It does not work to demonstrate this inside another chunk, so if you want to include it, see the link or check my code in the quant fundamentals book.

3.3.3 Callout blocks

My personal favourite features, you can highlight content with callout blocks. These range from notes that people might find interesting, to warnings that something could go mortally wrong.

::: {.callout-note}
These are notes.
:::

Note

These are notes.

You can change the title by using hashes within the callout. They count as real headers in the Quarto outline. So, if you use one hash, it looks like a level one header which deeply disturbs me, so I like to use four hashes to make more sense in the chapter structure.

::: {.callout-note}
#### Look at my interesting title
These are notes.
:::

Look at my interesting title

These are notes.

You can also make the box collapse by default, which can be handy to hide solutions or obscure tangents.

::: {.callout-note collapse=true}
#### Please look at me
Secret secret notes. 
:::

Please look at me

Secret secret notes.

Other types of callout blocks include:

Warning

::: {.callout-warning}
These are warnings.
:::

Warning

These are warnings.

Important

::: {.callout-important}
This is something important.
:::

Important

This is something important.

::: {.callout-tip}
Here is a handy tip. 
:::

Tip

Here is a handy tip.

And, a caution

::: {.callout-caution}
Here is a caution about something.
:::

Caution

Here is a caution about something.

3.3.4 References

If you want to add proper references instead of just hyperlinks, you need a .bib file from a reference manager.

The .bib file should be in the include folder (unless you point it somewhere else) and you can specify it in the _quarto.yml file through the bibliography entry:

bibliography: include/references.bib

How do I download and edit a .bib file?

I use Zotero as a reference manager and its super easy to download a .bib file for a project you are working on. Downloading one entry is a little annoying as you need to export it as BibTex and copy from the file it produces, but if you create a folder to store everything for the book, you can just export the folder each time you add new entries (right click >> export collection >> BibTex format and OK).

If you do have the single entry, you can open the .bib file within RStudio and copy the entry in. It will look something like this:

@article{bartlett_power_2022,
    title = {Power to the {People}: {A} {Beginner}’s {Tutorial} to {Power} {Analysis} using jamovi},
    volume = {6}
    ...}

which stores all the information for the .csl to pull out and cite/reference as needed.

To cite, you need the code at the start of the bib entry. For example, @bartlett_power_2022 produces Bartlett & Charles (2022) and the full reference will be added to the references chapter.

Depending on the citation style you want, there are different codes, such as adding it in parentheses [@bartlett_power_2022] (Bartlett & Charles, 2022). For a full list of options, you can check out the Quarto citation guide.

By default, the book template has APA style for referencing, but if you need a different referencing style, you can add and specify a different .csl file within _quarto.yml.

csl: include/apa.csl

How do I specify a .csl file?

.csl stands for citation style language and you can download one from the Zotero style repository. For example, you could search for vancouver, click on the link, and it will download a new .csl file you can add to your repository within include/.

3.3.5 `webexercises` interactive questions

The book template automatically includes the webexercises package which can add interactive questions for self-tests. This is great for students checking their understanding through MCQs or adding easy to check answers like numbers.

3.3.5.1 MCQs

You can add questions through inline code, or by first specifying them in an R code block if it makes it easier to edit longer text.

For example, this workshop is:

Life changing Boring Mediocre OK

`r longmcq(c(answer = "Life changing", "Boring", "Mediocre", "OK"))`

3.3.5.2 Single answer

You can ask simple single answers that are easy to evaluate:

On a scale of 1 (very dissatisfied) - 7 (very satisfied), how pleased are you with this workshop?

`r fitb(7)`

3.3.5.3 True or false

If you want an even simpler response, you can ask true or false.

After the workshop, I am going to make my own book:

`r torf(TRUE)`

3.3.6 Embedding files to download

Using a similar format to creating hyperlinks, you can embed files for people to download and use in the chapter. This can be really useful for student activities as you can give them a data set to follow along to your tutorials with.

First, you need to add a file within your book directory. If you have loads of data or files across your book, you might want a separate folder (I call mine data or supporting), but I have put a simple .csv in the include/ folder.

If you click on .csv file, it will download to your browser or people might need to right click and “save link as”. It follows the same format as hyperlinks:

click on [.csv file](include/test_data.csv)

3.3.7 Adding a glossary

Another cool feature that Lisa created is adding a glossary of terms. glossary is its own R package, but by default booktem includes it. You have two options, you can either add your own definitions as you go along, or if you are teaching data skills, you can use the PsyTeachR glossary.

Important

You still need to add definitions for anything that is not included in the PsyTeachR glossary. If you try and render and the item does not exist, you will get an error and you will need to manually add the definition within the inline code.

There are two main components to creating a glossary. First, you need to add glossary items as you work through your chapter using inline code. For example, I might want to define what a glossaryAn alphabetical list of words with explanations. is:

`r glossary("glossary", def = "An alphabetical list of words with explanations.")`

If you hover or click on the text, you will see the definition appear. There are different settings for this, so make sure you check the glossary documentation.

At the end of each chapter, you can then include a glossary table which shows all the words you used in the chapter. Just make sure you add echo=FALSE to the code chunk, so that the function does not appear.

```{r}
glossary_table()
```

This produces:

term	definition
glossary	An alphabetical list of words with explanations.

The behaviour of glossary table and whether you use all your own definitions or point to the PsyTeachR glossary is controlled by some R code in the booktem files. It will be easier to point out in the workshop, but you are looking for R/my_setup.R.

You can add definitions as you go along with inline code, or you can create and edit a .yml file for your terms if you would prefer to edit that way. See the glossary documentation for more information.

3.1 Quarto guide

3.2 Worked examples

3.3 Useful features

3.3.1 Markdown

3.3.1.1 Headers

3.3.1.1.1 Header extra formatting

3.3.1.2 Text formatting

3.3.1.3 Links

3.3.1.4 Internal hyperlinks

3.3.1.5 Images

3.3.2 Code chunks

3.3.3 Callout blocks

3.3.4 References

3.3.5 webexercises interactive questions

3.3.5.1 MCQs

3.3.5.2 Single answer

3.3.5.3 True or false

3.3.6 Embedding files to download

3.3.7 Adding a glossary

3.3.5 `webexercises` interactive questions