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.

Webexercises is an R package. 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 an R 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>

Similar as with H5P, it is sometimes also possible to embed Grasple exercises within a Quarto book, but only if allowed by the organisation using it. You can read more in the Grasple documentation on embedding.

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.

Buttons in Quarto are not actually Quarto-native. But because of Quarto’s flexibility it is easy to add one!

A regular button: 
[Check out Quarto](https://quarto.org/){.btn .btn-outline-primary .btn role="button"}

A button with a tooltip: 
[Check out Quarto](https://quarto.org/){.btn .btn-outline-primary .btn role="button" data-toggle="tooltip" title="Here's a tooltip"}

A regular button: Check out Quarto

A button with a tooltip: Check out Quarto (source)

If you want to make content stand out a bit more, Quarto has 5 default callout blocks: note, warning, important, tip and caution. They are formatted in different colors and you can make them appear simple, make them collapsible, and even referenceable throughout your book!

Example

:::{.callout-note collapse="true" title="Title of the note"}
Here is a note
:::

Here is a note

See for more information Quarto’s callout documentation.

7.4 Glossary

In-built support for creating glossaries is currently not available, but Lisa DeBruine has created a Quarto extension that uses the same logic as her previous glossary R package.

To use the glossary extension:

  1. First install the extension via the terminal:

    quarto install extension debruine/quarto-glossary

  2. Store definitions in a glossary file (YAML)

  3. To the _quarto.yml, add glossary metadata that specifies where the YAML file is located and how term definitions should appear.

  4. Use the extension:

    1. Use terms in your text with the shortcode

      



{{< glossary your-term >}}

    2. Display the whole glossary in a table

      



{{< glossary table = true >}}

For more extensive information, please refer to the full extension 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.