7  Interactivity

Interactivity can bring your book alive! There are numerous ways to add interactivity. Below we mention a couple, but keep in mind that this list is not complete, and to only add those elements that make sense for you!

Note

Keep in mind that most of the interactive elements mentioned here are only suitable for HTML output, i.e. online books. If you export the Quarto book to pdf, not much will remain of these elements!

7.1 Exercises

Interactive exercises are not part of core Quarto functionality. Luckily, there are smart people who have developed software packages to still include these. Here we go into two R packages: webexercises and learnr

According to the webexercises documentation:

webexercises creates standalone HTML files that require only a JavaScript-enabled browser. It is also extremely simple to use.

To get started, take the following steps:

  1. Install and load the package

    ```{r}
#| echo: false
install.packages("webexercises")
library(webexercises)
```

  2. Add the necessary files and setup to include webexercises in the Quarto project. You should only do this once so this does not need to be included in the .qmd files!

    add_to_quarto()

  3. Start using the exercises!

    1. Fill-in-the-blanks:

      Fill in any vowel: `r fitb(c("A", "E", "I", "O" , "U"), ignore_case = TRUE)`

      Fill in any vowel:

    2. Multiple choice:

      Which package helps you load data? 
`r mcq(c("tidyr", "dplyr", answer = "readr", "ggplot2"))`

      Which package helps you load data?

    3. See the webexercises documentation for other options:

      • True or false questions
      • Long multiple choice questions
      • Checked sections with feedback that can be hidden and unhidden
      • Hidden solutions and hints

learnr is a package that can turn markdown documents into interactive tutorials, including:

  • Narrative, figures, illustrations, and equations.
  • Code exercises (R code chunks that users can edit and execute directly).
  • Quiz questions.
  • Videos (supported services include YouTube and Vimeo).
  • Interactive Shiny components.

Source: learnr documentation

learnr in essence creates a Shiny application which must be hosted on a shiny server or run locally. The learnr documentation includes detailed instructions on how to create a tutorial.

Warning

Creating a tutorial with learnr requires you to host your tutorial on a shinyapp server. It is therefore not necessarily a core part of your Quarto book.

If H5P content is hosted on a public website, you can easily re-use it, by clicking “<> Embed” and copy-pasting the HTML code into your Quarto document!

Below is an example from the H5P.org website.

<iframe src="https://h5p.org/h5p/embed/6725" 
width="1090" height="389" frameborder="0" 
allowfullscreen="allowfullscreen" 
allow="geolocation *; microphone *; camera *; midi *; encrypted-media *"
title="Arithmetic Quiz"></iframe><script src="https://h5p.org/sites/all/modules/h5p/library/js/h5p-resizer.js" charset="UTF-8"></script>

7.2 Commenting on book content

It’s possible to allow others to comment on your book content. The comments will then be visible publicly for everyone in the book itself:

Through Hypothes.is, anyone can comment on content just like in Microsoft Office solutions, by selecting text and writing a comment about that text. People will need a Hypothes.is account in order to be able to comment, and all comments will be publicly visible.

Requirements: simply add the following on a new line in your _quarto.yml file:

comments:
    hypothesis: true

Or for further custom options, please refer to the Quarto documentation on Hypothes.is.

Utterances enables comments to be added to the bottom of a page. Comments on a page will automatically open as an Issue in the corresponding GitHub repository. People will need a GitHub account in order to be able to comment, and all comments will be publicly visible.

Requirements:

  • Make sure the GitHub repository is public (not private or internal).

  • Install the utterances app in the repository.

  • Make sure the Issue feature is enabled in the repository.

  • Add and adjust the following at the top of the chapter (.qmd file) where you want people to be able to comment:

    ---
format:
    html:
        comments:
            utterances:
                repo: yourusername/yourrepositoryname
---

  • Underneath repo, you can additionally specify label, theme, and issue-term, see the Quarto documentation.

Giscus enables comments to be added to the bottom of a page. Comments on a page will automatically open as a GitHub Discussion in the corresponding GitHub repository. People will need a GitHub account in order to be able to comment, and all comments will be publicly visible.

Requirements:

  • Make sure the GitHub repository is public (not private or internal).

  • Install the giscus app in the repository.

  • Make sure the GitHub Discussions feature is enabled in the repository.

  • Add and adjust the following at the top of the chapter (.qmd file) where you want people to be able to comment:

    ---
format:
    html:
        comments:
            giscus:
                repo: yourusername/yourrepositoryname
---

  • Underneath repo, you can additionally specify category, mapping, theme, language, and more settings, see the Quarto documentation.

7.3 HTML elements

Tabsets are a nice way to present different options. They are used on this page as well. To create them, use the following:

::: {.panel-tabset}
#### Tab number 1

Some content in tab number 1

#### Tab number 2

Some content in tab number 2

:::

You can read more about tabsets in the Quarto documentation.

Dropdown elements are a nice way to hide a lot of optional text. An example:

Click for more information
Here is some more information

Dropdowns like this are created with the HTML details tag. For example, the above example was created as follows:

<details><summary>Click for more information</summary>
<div>Here is some more information</div>
</details>

Everything about this details tag can be styled. That is too much to go into here, but you can find more information about that on the Mozilla Developer website.

… [WIP]

7.4 Glossary

In-built support for creating glossaries is currently not available, but on the roadmap for Quarto v1.5 (at the time of writing we are in Quarto v1.4). In the meantime, you can make use of the glossary R package written and maintained by Lisa DeBruine.

  1. Install and load the package

    ```{r}
#| echo: false
# Install the package
install.packages("glossary")

# Load the package
library(glossary)
```

  2. Add a glossary.yml file to your repository, see the documentation for an example. Also make sure the package knows where to find the glossary.yml file by adding:

    ```{r}
#| echo: false
# Let the glossary package know where the glossary.yml file is
glossary_path("glossary.yml")
```

  3. Check and update the glossary settings

    ```{r}
#| echo: false
# Set pop-up style for in-line terms
glossary_popup("hover") # Can also be "click" or "none"

# Glossary style: adjust where necessary
glossary_style(color = "purple", 
           text_decoration = "underline",
           def_bg = "#333",
           def_color = "white")
```

  4. Use the glossary:

    • In-line:

      Here I am typing `r glossary(my-glossary-term)` in the plain text.

    • All glossary terms in a table:

      ```{r}
#| echo: false
# Create glossary table
glossary_table()
```

For more extensive information, please refer to the full package documentation.

7.5 More advanced interactivity

It is possible to add interactivity in other ways too:

  • Create custom JavaScript visualizations using Observable JS

  • Use the Shiny R package to add interactivity to Knitr engine documents.

  • Incorporate Jupyter Widgets or htmlwidgets (for the Jupyter and Knitr engines, respectively) into your document.

Please refer to the extensive Quarto documentation for information on how to implement these into your Quarto book or website.