man/revealjs_presentation.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/revealjs_presentation.R
\name{revealjs_presentation}
\alias{revealjs_presentation}
\title{Convert to a reveal.js presentation}
\usage{
revealjs_presentation(
  incremental = FALSE,
  center = FALSE,
  slide_level = 2,
  chapter_numbering = TRUE,
  toc = FALSE,
  toc_depth = 3,
  fig_width = 8,
  fig_height = 6,
  fig_retina = if (!fig_caption) 2,
  fig_caption = FALSE,
  self_contained = FALSE,
  theme = "ids",
  transition = "convex",
  background_transition = "fade",
  reveal_options = NULL,
  reveal_plugins = c("notes", "search", "menu", "zoom"),
  highlight = "default",
  df_print = "kable",
  mathjax = "default",
  template = "default",
  css = NULL,
  includes = NULL,
  keep_md = FALSE,
  lib_dir = NULL,
  pandoc_args = NULL,
  extra_dependencies = NULL,
  md_extensions = NULL,
  ...
)
}
\arguments{
\item{incremental}{\code{TRUE} to render slide bullets incrementally. Note
that if you want to reverse the default incremental behavior for an
individual bullet you can precede it with \code{>}. For example:
\emph{\verb{> - Bullet Text}}. See more in
\href{https://pandoc.org/MANUAL.html#incremental-lists}{Pandoc's Manual}}

\item{center}{\code{TRUE} to vertically center content on slides}

\item{slide_level}{Level of heading to denote individual slides. If
\code{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. It is not recommended that you use deeper nesting of
section levels with reveal.js.}

\item{chapter_numbering}{\code{TRUE} (the default) numbers the \verb{#} chapter
headings automatically ("1. Introduction", "2. Methods", ...), skipping
references, appendix and thank-you chapters. \code{FALSE} turns the numbering
off -- headings keep exactly what was typed, including any manually
typed numbers. A number starts the enumeration at that value:
\code{chapter_numbering = 5} numbers the first chapter "5." (useful for
continuation decks).}

\item{toc}{\code{TRUE} to include a table of contents in the output (only
level 1 headers will be included in the table of contents).}

\item{toc_depth}{Depth of headers to include in table of contents}

\item{fig_width}{Default width (in inches) for figures}

\item{fig_height}{Default height (in inches) for figures}

\item{fig_retina}{Scaling to perform for retina displays (defaults to 2, which
currently works for all widely used retina displays). Set to \code{NULL} to
prevent retina scaling. Note that this will always be \code{NULL} when
\code{keep_md} is specified (this is because \code{fig_retina} relies on
outputting HTML directly into the markdown document).}

\item{fig_caption}{\code{TRUE} to render figures with captions}

\item{self_contained}{Whether to generate a full LaTeX document (\code{TRUE})
or just the body of a LaTeX document (\code{FALSE}). Note the LaTeX
document is an intermediate file unless \code{keep_tex = TRUE}.}

\item{theme}{Visual theme. The dedicated IDS corporate design theme
("ids") is the default and the only supported theme.}

\item{transition}{Slide transition (
"convex", "fade", "slide", "concave", "zoom", or "none"
)}

\item{background_transition}{Slide background-transition (
"convex", "fade", "slide", "concave", "zoom", or "none"
)}

\item{reveal_options}{Additional options to specify for reveal.js (see
\url{https://revealjs.com/config/} for details). Options for plugins can also
be passed, using plugin name as first level key (e.g \code{list(slideNumber = FALSE, menu = list(number = TRUE))}).}

\item{reveal_plugins}{Reveal plugins to include. Available plugins include
"notes", "search", "zoom", "chalkboard", and "menu". Defaults to
\code{c("notes", "search", "menu", "zoom")}; pass \code{NULL} to render without
any plugins. Note that \code{self_contained} must be set to \code{FALSE} in order
to use Reveal plugins.}

\item{highlight}{Syntax highlighting style passed to Pandoc.

 Supported built-in styles include "default", "tango", "pygments", "kate",
 "monochrome", "espresso", "zenburn", "haddock", and "breezedark".

  Two custom styles are also included, "arrow", an accessible color scheme,
  and "rstudio", which mimics the default IDE theme. Alternatively, supply a
  path to a \samp{.theme} file to use
  \href{https://pandoc.org/MANUAL.html#syntax-highlighting}{a custom Pandoc
  style}. Note that custom theme requires Pandoc 2.0+.

  Pass \code{NULL} to prevent syntax highlighting.}

\item{df_print}{Method used to print data frames in the document. The
default, \code{"kable"}, renders data frames as plain HTML tables styled by
the presentation theme, so that results look reasonable on slides without
any extra code. Since \code{"kable"} prints all rows, consider showing only
\code{head(x)} on slides with many-rowed results. Other supported methods are
\code{"default"} (plain text output), \code{"tibble"}, and \code{"paged"} (an
interactive paged table, see \code{\link[rmarkdown:html_document]{rmarkdown::html_document()}}).}

\item{mathjax}{Include mathjax. The "default" option uses an https URL from a
MathJax CDN. The "local" option uses a local version of MathJax (which is
copied into the output directory). You can pass an alternate URL or pass
\code{NULL} to exclude MathJax entirely.}

\item{template}{Pandoc template to use for rendering. Pass "default" to use
the rmarkdown package default template; pass \code{NULL} to use pandoc's
built-in template; pass a path to use a custom template that you've
created. Note that if you don't use the "default" template then some
features of \code{revealjs_presentation} won't be available (see the
Templates section below for more details).}

\item{css}{CSS and/or Sass files to include. Files with an extension of .sass
or .scss are compiled to CSS via \code{sass::sass()}. Also, if \code{theme} is a
\code{\link[bslib:bs_theme]{bslib::bs_theme()}} object, Sass code may reference the relevant Bootstrap
Sass variables, functions, mixins, etc.}

\item{includes}{Named list of additional content to include within the
document (typically created using the \code{\link[rmarkdown]{includes}} function).}

\item{keep_md}{Keep the markdown file generated by knitting.}

\item{lib_dir}{Directory to copy dependent HTML libraries (e.g. jquery,
bootstrap, etc.) into. By default this will be the name of the document with
\verb{_files} appended to it.}

\item{pandoc_args}{Additional command line options to pass to pandoc}

\item{extra_dependencies}{Additional function arguments to pass to the base R
Markdown HTML output formatter \code{\link[rmarkdown:html_document_base]{rmarkdown::html_document_base()}}.}

\item{md_extensions}{Markdown extensions to be added or removed from the
default definition of R Markdown. See the \code{\link[rmarkdown]{rmarkdown_format}} for
additional details.}

\item{...}{Ignored}
}
\value{
R Markdown output format to pass to \code{\link[rmarkdown:render]{rmarkdown::render()}}
}
\description{
Format for converting from R Markdown to a reveal.js presentation.
}
\details{
In reveal.js presentations you can use level 1 or level 2 headers for slides.
If you use a mix of level 1 and level 2 headers then a two-dimensional layout
will be produced, with level 1 headers building horizontally and level 2
headers building vertically.

For additional documentation on using revealjs presentations see
\url{https://github.com/rstudio/revealjs}
}
\section{About plugins}{
The plugins \code{notes}, \code{search}, \code{menu} and \code{zoom} are activated by default;
only \code{chalkboard} is opt-in. Setting \code{reveal_plugins} replaces the default
set -- pass \code{NULL} to render without any plugins.
\subsection{Built-in plugins with reveal.js}{
\subsection{Zoom}{

Activated by default: ALT + Click can be used to zoom on a slide.
}

\subsection{Notes}{

Activated by default: shows a \href{https://revealjs.com/speaker-view/}{speaker view} in a separated
window. This speaker view contains a timer, current slide, next slide, and
speaker notes. It also duplicate the window to have presentation mode
synchronized with main presentation.

Use

\if{html}{\out{<div class="sourceCode markdown">}}\preformatted{::: notes
Content of speaker notes
:::
}\if{html}{\out{</div>}}

to create notes only viewable in presentation mode. Notes placed before
the first heading are attached to the title slide.

On mobile browsers (touch devices), a button next to the fullscreen
toggle overlays the current slide with its speaker notes (plus the slide
title and, if present, the planned time from a timing comment), which is
useful for practicing a talk on a phone or tablet. It follows along as
you change slides and only appears if the deck contains notes at all.

Pressing \code{r} -- or, on touch devices, tapping the list button next to
the speaker notes button -- toggles a transcript view: a single
scrollable page containing every slide's content and speaker notes.
Text-to-speech ("read aloud") browser extensions cannot walk a
reveal.js deck, since hidden slides are not part of the visible page
text -- the transcript gives them something they can read from start
to finish.
}

}

\subsection{Slide timing}{

Speaker time can be planned per slide and per speaker by adding a comment
with a speaker code and the expected duration (in \code{MM:SS}, \code{HH:MM:SS}, or
plain seconds format) anywhere inside a slide:

\if{html}{\out{<div class="sourceCode markdown">}}\preformatted{## My slide title

Some content

<!-- MK 00:30 -->
}\if{html}{\out{</div>}}

This means Marc Kupietz will need 30 seconds for that slide. For talks
presented by a single speaker, the speaker code can be omitted:
\verb{<!-- 00:30 -->}. Comments placed before the first heading are applied to
the title slide.

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

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{output:
  revealjs.ids::revealjs_presentation:
    reveal_options:
      totalTime: 3600 # one hour
}\if{html}{\out{</div>}}

During rendering, comments are converted into \code{data-timing} attributes on
the slides' \verb{<section>} elements (several speakers per slide are summed
up), and the calculated grand total is passed to reveal.js as the
\code{totalTime} config value. This activates the pacing timer in the
\href{https://revealjs.com/speaker-view/}{speaker view}, which shows how you
are doing relative to your plan. A summary of the total time per speaker
is printed during rendering. If the document sets \code{totalTime} or
\code{defaultTiming} itself (via \code{reveal_options}), those take precedence.

The function \code{\link[=slide_timing]{slide_timing()}} computes these totals directly from an
\code{.Rmd} source file without rendering it.
}

\subsection{Vertical content centering}{

Slides with little content look lost when everything is glued below the
title bar, while packed slides must start at the top. reveal.js' own
\code{center} option cannot express this -- it also vertically centers the
headings. Instead, the body content of each slide (everything after the
heading block except speaker notes) is grouped and, whenever there is
free space, centered in the area between the heading and the footer:
slides that are too packed simply start directly below the heading and
overflow downwards, exactly as before. Centered content never reaches
into the footer; content too tall to fit above it may, as it always
could. Heading-only section-divider slides keep their own centered-title
layout. No configuration is needed and nothing changes about how slides
are authored.
}

\subsection{Chapter numbering}{

Like in the old Google Docs slide workflow, chapter headings (\verb{#}) are
numbered automatically: 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 (\verb{# 2. Methods}) are stripped before
renumbering, so decks migrated from the old pipeline and repeated
numbering runs stay stable. The numbers are added when the presentation
is opened: the menu plugin and the transcript view show them, too, and
the overview slide's table of contents uses them as its ordered list's
enumeration. Decks rendered with \code{slide_level = 1} (one \verb{#} heading per
slide) are left unnumbered -- there, headings denote slides, not
chapters. The numbering can be turned off with \code{chapter_numbering: false}
in the yaml header, or started at another number with e.g.
\code{chapter_numbering: 5} (useful for continuation decks).
}

\subsection{Overview slides}{

Like in the original Google Docs slide workflow, a slide titled
"Overview" or "Überblick" is automatically turned into a table of
contents: its body content is replaced at presentation time with a
clickable, ordered list of all \verb{#} chapter headings, whose enumeration
repeats the chapter numbers. Adding
\code{{data-overview-subheadings=true}} to the heading also includes the
\verb{##} sub-headings below their chapters, laid out in two columns.
References, appendix and thank-you chapters (References/Literatur/
Literaturverzeichnis/Referenzen/Publikationen/Herausgeberschaften/
Appendix/Anhang, and headings containing "Thank you"/"Vielen Dank") are
left out, together with their sub-slides.
\subsection{Search}{

Activated by default: pressing \code{CTRL + SHIFT + F} shows a search box.
It will search in the whole presentation, and highlight matched words. The
matches will also be highlighted in overview mode (pressing ESC to see all
slides in one scrollable view)
}

}

\subsection{Menu}{

Activated by default: a slideout menu plugin for Reveal.js to quickly jump
to any slide by title.

Version  is
currently used and documentation for configurations can be found at
\href{https://github.com/denehyg/reveal.js-menu/blob/2.1.0/README.md}{denehyg/reveal.js-menu}
\subsection{Known limitations}{

Some configurations cannot be modified in the current template:
\itemize{
\item \code{loadIcons: false}  the fontawesome icons are loaded by \pkg{rmarkdown}
when this plugin is used
\item \code{custom: false}
\item \code{themes: false}
\item \code{transitions: false}
}
}

}

\subsection{Chalkboard}{

An opt-in plugin adding a chalkboard and slide annotation

Version  is
currently used and documentation for configurations can be found at
\href{https://github.com/rajgoel/reveal.js-plugins/tree/4.2.5/4.1.5/chalkboard}{rajgoel/reveal.js-plugins}

By default, chalkboard and annotations modes will be accessible using keyboard
shortcuts, respectively, pressing B, or pressing C.
In addition, buttons on the bottom left can be added by using the following

\if{html}{\out{<div class="sourceCode yaml">}}\preformatted{reveal_plugins: 
  - chalkboard
reveal_options:
  chalkboard:
    toggleNotesButton: true
    toggleChalkboardButton: true
}\if{html}{\out{</div>}}
}

\subsection{Title slide: QR code and additional logos}{

Three optional yaml entries personalise the title slide for external
audiences (ported from \pkg{posterdown.ids}):
\itemize{
\item \verb{website: <url>} -- a linked QR code pointing to the URL is placed in
the top left of the title slide. Uses the \pkg{qrcode} package.
\item \verb{partner_logo: <path-or-url>} -- when a presentation is given by
authors from two institutions, the partner institution's logo is shown
next to the IDS logo, in the top right of every slide.
\item \verb{funder_logo: <path-or-url>} -- a funder logo (e.g. "Text+") is placed
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
URLs are used as-is. A QR code anywhere else on a slide can be produced
with \code{\link[=qrlink]{qrlink()}} from inline R code. The navigation chrome (arrows, slide
number, menu button) is hidden on the title slide for a bare first
impression.
}

\subsection{Bibliography and citations}{

Documents with a \verb{bibliography:} in their YAML header are formatted with
the bundled IDS citation style (\code{ids.csl}, based on the style developed
for ICLC-10 2023 in Mannheim) by default. To use a different style,
specify it as usual with \verb{csl:} in the YAML header.
}
}

\examples{
\dontrun{

library(rmarkdown)
library(revealjs.ids)

# simple invocation
render("pres.Rmd", revealjs_presentation())

# specify an option for incremental rendering
render("pres.Rmd", revealjs_presentation(incremental = TRUE))
}

}