README.Rmd

---
title: "R Markdown Format for reveal.js Presentations – Extended by an IDS Mannheim CD Theme"
output: github_document
---

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/revealjs)](https://CRAN.R-project.org/package=revealjs)
[![R-CMD-check](https://github.com/rstudio/revealjs/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/rstudio/revealjs/actions/workflows/R-CMD-check.yaml)
[![reveal.js](https://img.shields.io/badge/reveal.js-`r revealjs.ids:::revealjs_version()`-yellow)](https://github.com/rstudio/revealjs/tree/main/inst/reveal.js-`r revealjs.ids:::revealjs_version()`)
<!-- badges: end -->

## Screenshots

Generated from [examples/ids.Rmd](./examples/ids.Rmd), see live demo [here](http://10.0.1.45/slides/2023-10-08-Revealjs-demo/ids.html). A small starting-point deck is [examples/minimal.Rmd](./examples/minimal.Rmd).

![title](https://gitlab.ids-mannheim.de/ids/revealjs/-/jobs/artifacts/main/raw/target/title.png?job=build-job)

![users](https://gitlab.ids-mannheim.de/ids/revealjs/-/jobs/artifacts/main/raw/target/users.png?job=build-job)
![collocates](https://gitlab.ids-mannheim.de/ids/revealjs/-/jobs/artifacts/main/raw/target/ca.png?job=build-job)

![references](https://gitlab.ids-mannheim.de/ids/revealjs/-/jobs/artifacts/main/raw/target/references.png?job=build-job)

## Overview

This repository provides an [R Markdown](http://rmarkdown.rstudio.com) custom format for [reveal.js](https://revealjs.com/) HTML presentations. The packages includes _reveal.js_ library in version `r revealjs.ids:::revealjs_version()`

You can use this format in R Markdown documents by installing this package as follows:

``` r
remotes::install_git("https://korap.ids-mannheim.de/gerrit/IDS-Mannheim/revealjs")
```

> **Package renamed — migration note:** This package, the IDS corporate design fork of [rstudio/revealjs](https://github.com/rstudio/revealjs), was called `revealjs` before version 0.9.1.9009 and was renamed to `revealjs.ids` so that it can be installed alongside the upstream package. To migrate existing documents, replace `revealjs::revealjs_presentation` with `revealjs.ids::revealjs_presentation` in the YAML header. (Alternatively, install upstream `revealjs` and keep the old header for documents that should use the upstream format.)

To create a [reveal.js](https://revealjs.com/) presentation from R Markdown you specify the `revealjs_presentation` output format in the front-matter of your document. You can create a slide show broken up into sections by using the `#` and `##` heading tags (you can also create a new slide without a header using a horizontal rule (`----`). For example here's a simple slide show:

``` markdown
---
title: "Habits"
author: John Doe
date: March 22, 2005
output: revealjs.ids::revealjs_presentation
---

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

## Going to sleep

- Get in bed
- Count sheep
```

## Rendering

Depending on your use case, there are 3 ways you can render the presentation.

1.  RStudio
2.  R console
3.  Terminal (e.g., bash)

### RStudio

When creating the presentation in RStudio, there will be a `Knit` button right below the source tabs. By default, it will render the current document and place the rendered `HTML` file in the same directory as the source file, with the same name.

### R Console

The `Knit` button is actually calling the `rmarkdown::render()` function. So, to render the document within the R console:

``` r
rmarkdown::render('my_reveal_presentation.Rmd')
```

There are many other output tweaks you can use by directly calling `render`. You can read up on the [documentation](https://pkgs.rstudio.com/rmarkdown/reference/render.html) for more details.

### Command Line

When you need the presentation to be rendered from the command line:

``` bash
Rscript -e "rmarkdown::render('my_reveal_presentation.Rmd')"
```

## Display Modes

The following single character keyboard shortcuts enable alternate display modes:

-   `'f'` enable fullscreen mode

-   `'o'` enable overview mode

-   `'b'` enable pause mode with a black screen hiding slide content

-   `'?'` enable help mode to show keyboard shortcut cheatsheet

-   `'s'` enable presentation mode with speaker notes when the Notes plugin is activated

On mobile browsers (touch devices), a speech-bubble button next to the fullscreen button overlays the current slide with its speaker notes -- useful for practicing a talk on a phone or tablet, where the separate speaker view window of the `'s'` shortcut is awkward. The overlay shows the slide title, its planned time (if annotated with a timing comment), and the notes, and follows along as you change slides. It appears only if the deck contains notes at all. Next to it, a list button opens the transcript view (same as pressing `r`), so the whole talk including notes can be read (aloud) on mobile devices, too.

-   `'r'` toggle the transcript view: a single scrollable page containing every slide's content and speaker notes, so text-to-speech ("read aloud") browser extensions can read the whole presentation -- they cannot walk a reveal.js deck themselves, since hidden slides are not part of the visible page text

-   `'m'` enable menu mode when the 'menu' plugin is activated

Pressing `Esc` exits all of these modes.

## Slide Timing

You can plan the time budget of a talk by adding timing comments to your slides: a comment with an optional speaker code and the expected duration (`MM:SS`, `HH:MM:SS`, or plain seconds), ported from the old Google-Docs-based slide workflow:

``` markdown
## My slide title

Some content

<!-- JD 00:30 -->
```

This means John Doe will need 30 seconds for that slide. For talks presented by a single speaker, the speaker code can be omitted: Comments placed before the first heading are applied to the title slide, so you can give the title itself a time budget and a welcome note:

``` markdown
## My slide title

Some content

<!-- 00:30 -->
```

Typically you start from a known total time budget and adjust the individual slides to it. You can set this budget yourself with the `totalTime` option (in seconds):

``` yaml
output:
  revealjs.ids::revealjs_presentation:
    reveal_options:
      totalTime: 3600 # one hour
```

When rendering, the comments are converted into [`data-timing` attributes](https://revealjs.com/speaker-view/) on the slides, and the calculated grand total is passed to reveal.js as the `totalTime` config value (unless you set `totalTime` yourself). This activates the pacing timer in the [speaker view](https://revealjs.com/speaker-view/) (press `s`), showing how you are doing relative to your plan. Several speakers per slide are supported, and a summary with the total time per speaker is printed:

```
Slide timing -- JD: 0:30, AB: 1:00 -- total 1:30
```

To compute the time budget without rendering the presentation, you can call `slide_timing()` directly on the `.Rmd` source file.

## Overview Slides

Like in the old Google-Docs-based slide workflow, a slide titled "Overview" or "Überblick" is automatically turned into a table of contents: its body content is replaced with an ordered list of all `#` chapter headings, whose enumeration repeats the chapter numbers, and each entry links to the corresponding slide.

``` markdown
## Overview

(any placeholder content -- replaced automatically)
```

To also include the `##` sub-headings below their chapters, add `{data-overview-subheadings=true}` to the heading; the list is then laid out in two columns. References and appendix chapters (References/Literatur/Literaturverzeichnis/Appendix/Anhang) are left out, together with their sub-slides.

``` markdown
## Overview {data-overview-subheadings=true}
```

The TOC is generated when the presentation is opened, so it always reflects the deck it is part of. Slides without a heading and the title slide are left out.

## Chapter Numbering

Like in the old Google-Docs-based slide workflow, `#` chapter headings are numbered automatically when the presentation is opened: the first chapter becomes "1. Introduction", the second "2. Methods", and so on. References, appendix and thank-you chapters (References/Literatur/Referenzen/Publikationen/Herausgeberschaften/Appendix/Anhang, and headings containing "Thank you"/"Vielen Dank") keep their bare titles and are not counted. Manually typed leading numbers (`# 2. Methods`) are stripped before renumbering, so the numbering also comes out right in decks migrated from the old pipeline. Since the numbers are added to the headings themselves, they show up everywhere the headings do: the menu plugin and the transcript view, and on the overview slide they become the enumeration of the table of contents.

Decks with `slide_level: 1` (one `#` heading per slide) are left unnumbered -- there, headings denote slides, not chapters.

The numbering can be turned off with the `chapter_numbering` option -- headings then keep exactly what was typed:

``` yaml
output:
  revealjs.ids::revealjs_presentation:
    chapter_numbering: false
```

A number starts the enumeration at that value instead, which is useful for continuation decks:

``` yaml
output:
  revealjs.ids::revealjs_presentation:
    chapter_numbering: 5
```

## Vertical Content Centering

Slides with little content no longer sit glued below the title bar: whenever there is free space, the slide's body content is centered in the area between the heading and the footer. Slides that are too packed start directly below the heading and overflow downwards exactly as before, and centered content never covers the footer. Reveal.js' own `center` option could not be used for this, because it also vertically centers the headings. Heading-only section-divider slides keep their dedicated centered-title layout.

## Incremental Bullets

You can render bullets incrementally by adding the `incremental` option:

``` yaml
---
output:
  revealjs.ids::revealjs_presentation:
    incremental: true
---
```

If you want to render bullets incrementally for some slides but not others you can use this syntax:

``` markdown
::: incremental

- Eat spaghetti
- Drink wine

:::
```

or

``` markdown
::: nonincremental

- Eat spaghetti
- Drink wine

:::
```

## Incremental Revealing

You can also add pauses between content on a slide using `. . .`

``` markdown
# Slide header

Content shown first

. . .

Content shown next on the same slide
```

Using Fragments explicitly is also possible

``` markdown
# Slide header

Content shown first

::: fragment
Content shown next on the same slide
:::
```

## Appearance and Style

There are several options that control the appearance of revealjs presentations:

-   `theme` specifies the visual theme for the presentation. The dedicated IDS corporate design theme (`"ids"`) is the default and the only supported theme.

-   `highlight` specifies the syntax highlighting style. Supported styles include `r knitr::combine_words(rmarkdown:::highlighters(), before = '"', and = " or ")`. Pass null to prevent syntax highlighting.

-   `center` specifies whether you want to vertically center content on slides (this defaults to false).

For example:

``` yaml
output:
  revealjs.ids::revealjs_presentation:
    highlight: pygments
    center: true
```

## Title Slide: QR Code and Logos

Three optional yaml entries brand the title slide for external audiences:

``` yaml
title: "Habits"
website: "https://gitlab.ids-mannheim.de/ids/revealjs"
partner_logo: "dnb-logo.svg"
funder_logo: "textplus-logo.svg"
output: revealjs.ids::revealjs_presentation
```

-   `website` places a linked QR code (pointing to the URL) in the top left of the title slide. Requires the `qrcode` package.

-   `partner_logo`, a path or URL to a second institution's logo, shows it next to the IDS logo in the top right of *every* slide -- for presentations given by authors from two institutions.

-   `funder_logo`, a path or URL to a funder logo, shows it in the bottom left of the title slide, opposite the Leibniz Gemeinschaft membership logo. It is lifted above the footer band on print (pdf) pages.

Local logo files (svg, png, jpg, gif, webp) are embedded in the html as data URIs, so they do not need to be shipped with the presentation; http(s) URLs are used as-is. A linked QR code at any other place on a slide can be produced with `revealjs.ids::qrlink("https://...")` in inline R code. On the title slide the navigation chrome (arrows, slide number, menu button) is hidden, for a bare first impression.

## Slide Transitions

You can use the `transition` and `background_transition` options to specify the global default slide transition style:

-   `transition` specifies the visual effect when moving between slides. Available transitions are `r (trans <- knitr::combine_words(setdiff(revealjs.ids:::revealjs_transitions(), "default"), before = '"', and = " or "))`.

-   `background_transition` specifies the background transition effect when moving between full page slides. Available transitions are `r trans`

For example:

``` yaml
output:
  revealjs.ids::revealjs_presentation:
    transition: fade
    background_transition: slide
```

You can override the global transition for a specific slide by using the data-transition attribute, for example:

``` markdown
## Use a zoom transition {data-transition="zoom"}

## Use a faster speed {data-transition-speed="fast"}
```

You can also use different in and out transitions for the same slide, for example:

``` markdown
## Fade in, Slide out {data-transition="slide-in fade-out"}

## Slide in, Fade out {data-transition="fade-in slide-out"}
```

This works also for background transition

``` markdown
## Use a zoomed background transition {data-background-transition="zoom"}
```

[Revealjs documentation about transitions](https://revealjs.com/transitions/)

## Slide Backgrounds

Slides are contained within a limited portion of the screen by default to allow them to fit any display and scale uniformly. You can apply full page backgrounds outside of the slide area by adding a data-background attribute to your slide header element. Four different types of backgrounds are supported: color, image, video and iframe. Below are a few examples.

``` markdown
## CSS color background {data-background-color=#ff0000}

## Full size image background {data-background-image="background.jpeg"}

## Video background {data-background-video="background.mp4"}

## Embed a web page as a background {data-background-iframe="https://example.com"}
```

Backgrounds transition using a fade animation by default. This can be changed to a linear sliding transition by specifying the `background-transition: slide`. Alternatively you can set `data-background-transition` on any slide with a background to override that specific transition.

[Revealjs documentation about backgrounds](https://revealjs.com/backgrounds/)

## 2-D Presentations

You can use the `slide_level` option to specify which level of heading will be used to denote individual slides. If `slide_level` is 2 (the default), a two-dimensional layout will be produced, with level 1 headers building horizontally and level 2 headers building vertically. For example:

``` markdown
# Horizontal Slide 1

## Vertical Slide 1

## Vertical Slide 2

# Horizontal Slide 2
```

With this layout horizontal navigation will proceed directly from "Horizontal Slide 1" to "Horizontal Slide 2", with vertical navigation to "Vertical Slide 1", etc. presented as an option on "Horizontal Slide 1". Global reveal option [`navigationMode`](https://revealjs.com/vertical-slides/#navigation-mode) can be tweaked to change this behavior.

## Reveal Options

Reveal.js has many additional options to configure it's behavior. You can specify any of these options using `reveal_options`, for example:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    self_contained: false
    reveal_options:
      slideNumber: true
      previewLinks: true
---
```

You can find documentation on the various available Reveal.js options here: <https://revealjs.com/config/>.

## Figure Options

There are a number of options that affect the output of figures within reveal.js presentations:

-   `fig_width` and `fig_height` can be used to control the default figure width and height (7x5 is used by default)

-   `fig_retina` Specifies the scaling to perform for retina displays (defaults to 2, which currently works for all widely used retina displays). Note that this only takes effect if you are using knitr >= 1.5.21. Set to `null` to prevent retina scaling.

-   `fig_caption` controls whether figures are rendered with captions

For example:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    fig_width: 7
    fig_height: 6
    fig_caption: true
---
```

## Lightbox

reveal.js 5.2 added a [lightbox](https://revealjs.com/lightbox/): any element on a slide can be turned into a clickable trigger that opens an image or video full-size in a dimmed overlay, without leaving the slide. This is useful for dense figures or tables that should stay readable in the slide layout but be inspectable at full size during a presentation.

Add the corresponding data attribute to an image:

```markdown
![Figure](plot.png){data-preview-image}
```

or set it on knitr-generated figures via `out.extra`:

````markdown
```{r, out.extra='data-preview-image'}
plot(cars)
```
````

Clicking the image on the slide opens it full-size; `Esc` or another click closes the overlay.

## MathJax Equations

By default [MathJax](http://www.mathjax.org/) scripts are included in reveal.js presentations for rendering LaTeX and MathML equations. You can use the `mathjax` option to control how MathJax is included:

-   Specify "default" to use an https URL from the official MathJax CDN.

-   Specify "local" to use a local version of MathJax (which is copied into the output directory). Note that when using "local" you also need to set the `self_contained` option to false.

-   Specify an alternate URL to load MathJax from another location.

-   Specify null to exclude MathJax entirely.

For example, to use a local copy of MathJax:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    mathjax: local
    self_contained: false
---
```

To use a self-hosted copy of MathJax:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    mathjax: "http://example.com/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
---
```

To exclude MathJax entirely:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    mathjax: null
---
```

## Document Dependencies

By default R Markdown produces standalone HTML files with no external dependencies, using data: URIs to incorporate the contents of linked scripts, stylesheets, images, and videos. This means you can share or publish the file just like you share Office documents or PDFs. If you'd rather keep dependencies in external files you can specify `self_contained: false`. For example:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    self_contained: false
---
```

Note that even for self contained documents MathJax is still loaded externally (this is necessary because of it's size). If you want to serve MathJax locally then you should specify `mathjax: local` and `self_contained: false`.

One common reason keep dependencies external is for serving R Markdown documents from a website (external dependencies can be cached separately by browsers leading to faster page load times). In the case of serving multiple R Markdown documents you may also want to consolidate dependent library files (e.g. Bootstrap, MathJax, etc.) into a single directory shared by multiple documents. You can use the `lib_dir` option to do this, for example:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    self_contained: false
    lib_dir: libs
---
```

## Reveal Plugins

You can enable various reveal.js plugins using the `reveal_plugins` option. Plugins currently supported include:

| Plugin                                                                             | Description                                                                                                                           |
|------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
| [notes](https://revealjs.com/speaker-view/)                                        | Present per-slide notes in a separate browser window. Open Note view pressing `S`.                                                    |
| [zoom](http://lab.hakim.se/zoom-js/)                                               | Zoom in and out of selected content with `Alt+Click.`                                                                                 |
| [search](https://github.com/hakimel/reveal.js/blob/master/plugin/search/search.js) | Find a text string anywhere in the slides and show the next occurrence to the user. Open search box using `CTRL + SHIFT + F`.         |
| [chalkboard](https://github.com/rajgoel/reveal.js-plugins/tree/master/chalkboard)  | Include handwritten notes within a presentation. Press `c` to write on slides, Press `b` to open a whiteboard or chalkboard to write. |
| [menu](https://github.com/denehyg/reveal.js-menu)                                  | Include a navigation menu within a presentation. Press `m` to open the menu.                                                          |

The plugins `notes`, `search`, `menu`, and `zoom` are activated by default; only `chalkboard` is opt-in. Setting `reveal_plugins` yourself replaces the default set, so to add `chalkboard` while keeping the defaults, list them all explicitly. Set `reveal_plugins: null` to render without any plugins.

Note that the use of plugins requires that the `self_contained` option be set to false. For example, this presentation uses only the "notes" and "search" plugins (dropping "menu" and "zoom" from the default set):

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    self_contained: false
    reveal_plugins: ["notes", "search"]
---
```

You can specify additional options for the `chalkboard` and `menu` plugins using `reveal_options`, for example:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    self_contained: false
    reveal_plugins: ["chalkboard", "menu"]
    reveal_options:
      chalkboard:
        theme: whiteboard
        toggleNotesButton: false
      menu:
        side: right
---
```

No other plugins can be added in `revealjs_presentation()`. You can open feature request for new plugins or you would need to use a custom template to write your own HTML format including custom plugins.

## Bibliography and Appendix Slides

When you cite with `[@key]` and set a `bibliography:` in the yaml header, the references are formatted with the bundled IDS citation style by default (based on the style developed for ICLC-10 2023 in Mannheim). To use a different style, specify it as usual with `csl:` in the yaml header. The `ids` theme auto-fits the references slide: it tries decreasing font sizes and, when the bibliography is too long even for the smallest, moves trailing entries onto automatically created "References (cont.)" slides. When printing to PDF, the on-screen scroll box is disabled so long bibliographies flow across pages instead of being clipped.

Pandoc/citeproc generates the reference list **at the very end of the document body**. That is fine when the references are your last content:

```markdown
# References

## References
```

If you want slides to follow the references -- typically an appendix with spare slides -- the bibliography would otherwise end up inside your last appendix slide. Place it explicitly with a `::: {#refs}` fenced div, and the appendix forms its own chapter group after the references; navigation and slide numbering keep working:

```markdown
# References

## References

::: {#refs}
:::

# Appendix

## Spare slide

- Some backup material
```

The `{#refs}` placeholder itself does not produce a slide.

## Advanced Customization

### Includes

You can do more advanced customization of output by including additional HTML content or by replacing the core pandoc template entirely. To include content in the document header or before/after the document body you use the `includes` option as follows:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    includes:
      in_header: header.html
      before_body: doc_prefix.html
      after_body: doc_suffix.html
---
```

### Pandoc Arguments

If there are pandoc features you want to use that lack equivalents in the YAML options described above you can still use them by passing custom `pandoc_args`. For example:

``` yaml
---
title: "Habits"
output:
  revealjs.ids::revealjs_presentation:
    pandoc_args: [
      "--title-prefix", "Foo",
      "--id-prefix", "Bar"
    ]
---
```

Documentation on all available pandoc arguments can be found in the [pandoc user guide](https://pandoc.org/MANUAL.html#options).

## Shared Options

If you want to specify a set of default options to be shared by multiple documents within a directory you can include a file named `_output.yaml` within the directory. Note that no YAML delimiters or enclosing output object are used in this file. For example:

**\_output.yaml**

``` yaml
revealjs.ids::revealjs_presentation:
  transition: fade
  highlight: pygments
```

All documents located in the same directory as `_output.yaml` will inherit it's options. Options defined explicitly within documents will override those specified in the shared options file.

## Code of Conduct

Please note that the revealjs project is released with a [Contributor Code of Conduct](https://pkgs.rstudio.com/revealjs/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.