Overview

To create an ioslides presentation from R Markdown you specify the ioslides_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:

---
title: "Habits"
author: John Doe
date: March 22, 2005
output: ioslides_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

----

![picture of spaghetti](images/spaghetti.jpg)

## Going to sleep

- Get in bed
- Count sheep

You can add a subtitle to a slide or section by including text after the pipe (|) character. For example:

## Getting up | What I like to do first thing

Display Modes

The following single character keyboard shortcuts enable alternate display modes:

  • 'f' enable fullscreen mode

  • 'w' toggle widescreen mode

  • 'o' enable overview mode

  • 'h' enable code highlight mode

  • 'p' show presenter notes

Pressing Esc exits all of these modes. See the sections below on Code Highlighting and Presenter Mode for additional detail on those modes.

Incremental Bullets

You can render bullets incrementally by adding the incremental option:

---
output:
  ioslides_presentation:
    incremental: true
---

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

> - Eat eggs
> - Drink coffee

Visual Appearance

Presentation Size

You can display the presentation using a wider form factor using the widescreen option. You can specify that smaller text be used with the smaller option. For example:

---
output:
  ioslides_presentation:
    widescreen: true
    smaller: true
---

You can also enable the smaller option on a slide-by-slide basis by adding the .smaller attribute to the slide header:

## Getting up {.smaller}

Transition Speed

You can customize the speed of slide transitions using transition option. This can be “default”, “slower”, “faster”, or a numeric value with a number of seconds (e.g. 0.5) . For example:

---
output:
  ioslides_presentation:
    transition: slower
---

Build Slides

Slides can also have a .build attribute that indicate that their content should be displayed incrementally. For example:

## Getting up {.build}

Slide attributes can be combined if you need to specify more than one, for example:

## Getting up {.smaller .build}

Custom CSS

You can add your own CSS to an ioslides presentation using the css option:

---
output:
  ioslides_presentation:
    css: styles.css
---

You can also target specific slides or classes of slice with custom CSS by adding ids or classes to the slides headers within your document. For example the following slide header:

## Next Steps {#nextsteps .emphasized}

Would enable you to apply CSS to all of it’s content using either of the following CSS selectors:

#nextsteps {
   color: blue;
}

.emphasized {
   font-size: 1.2em;
}

Code Highlighting

It’s possible to select subsets of code for additional emphasis by adding a special “highlight” comment around the code. For example:

### <b>
x <- 10
y <- x * 2
### </b>

The highlighted region will be displayed with a bold font. When you want to help the audience focus exclusively on the highlighted region press the 'h' key and the rest of the code will fade away.

Tables

The ioslides template has an attractive default style for tables so you shouldn’t hesitate to add tables for presenting more complex sets of information. Pandoc markdown supports several syntaxes for defining tables which are described in the pandoc markdown specification.

Advanced Layout

You can center content on a slide by adding the .flexbox and .vcenter attributes to the slide title. For example:

## Dinner {.flexbox .vcenter}

You can horizontally center content by enclosing it in a div tag with class centered. For example:

<div class="centered">
This text is centered.
</div>

You can do a two-column layout using the columns-2 class. For example:

<div class="columns-2">
  ![](image.png)

  - Bullet 1
  - Bullet 2
  - Bullet 3
</div>

Note that content will flow across the columns so if you want to have an image on one side and text on the other you should make sure that the image has sufficient height to force the text to the other side of the slide.

Text Color

You can color content using base color classes red, blue, green, yellow, and gray (or variations of them e.g. red2, red3, blue2, blue3, etc.). For example:

<div class="red2">
This text is red
</div>

Presenter Mode

A separate presenter window can also be opened (ideal for when you are presenting on one screen but have another screen that’s private to you). The window stays in sync with the main presentation window and also shows presenter notes and a thumbnail of the next slide. To enable presenter mode add ?presentme=true to the URL of the presentation, for example:

mypresentation.html?presentme=true

The presenter mode window will open and will always re-open with the presentation until it’s disabled with:

mypresentation.html?presentme=false

To add presenter notes to a slide you include it within a “notes” div. For example:

<div class="notes">
This is my *note*.

- It can contain markdown
- like this list

</div>

Printing and PDF Output

You can print an ioslides presentation from within browsers that have good support for print CSS (i.e. as of this writing Google Chrome has the best support). Printing maintains most of the visual styles of the HTML version of the presentation.

To create a PDF version of a presentation you can use Print to PDF from Google Chrome.

Figure Options

There are a number of options that affect the output of figures within ioslides 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

  • dev controls the graphics device used to render figures (defaults to png)

For example:

---
title: "Habits"
output:
  ioslides_presentation:
    fig_width: 7
    fig_height: 6
    fig_caption: true
---

Data Frame Printing

You can enhance the default display of data frames via the df_print option. Valid values include:

Option Description
default Call the print.data.frame generic method
kable Use the knitr::kable function.
tibble Use the tibble::print.tbl_df function.
paged Create a pageable HTML table

For example:

---
title: "Habits"
output:
  html_document:
    df_print: paged
---

MathJax Equations

By default MathJax scripts are included in ioslides 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:

---
title: "Habits"
output:
  ioslides_presentation:
    mathjax: local
    self_contained: false
---

To use a self-hosted copy of MathJax:

---
title: "Habits"
output:
  ioslides_presentation:
    mathjax: "http://example.com/mathjax/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
---

To exclude MathJax entirely:

---
title: "Habits"
output:
  ioslides_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 have keep depenencies in external files you can specify self_contained: false. For example:

---
title: "Habits"
output:
  ioslides_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:

---
title: "Habits"
output:
  ioslides_presentation:
    self_contained: false
    lib_dir: libs
---

Advanced Customization

Keeping Markdown

When knitr processes an R Markdown input file it creates a markdown (md) file which is subsequently tranformed into HTML by pandoc. If you want to keep a copy of the markdown file after rendering you can do so using the keep_md option:

---
title: "Habits"
output:
  ioslides_presentation:
    keep_md: true
---

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:

---
title: "Habits"
output:
  ioslides_presentation:
    includes:
      in_header: header.html
      before_body: doc_prefix.html
      after_body: doc_suffix.html
---

Custom Templates

You can also replace the underlying pandoc template using the template option:

---
title: "Habits"
output:
  ioslides_presentation:
    template: quarterly_report.html
---

Consult the documentation on pandoc templates for additional details on templates. You can also study the default HTML template as an example.

The level of customisation that can be achieved is limited. The slides are generated by custom formatting written in Lua and as such the template used must include the string RENDERED_SLIDES as can be found in the file with path rmarkdown:::rmarkdown_system_file("rmd/ioslides/default.html").

Markdown Extensions

By default R Markdown is defined as all pandoc markdown extensions with the following tweaks for backward compatibility with the markdown package:

+autolink_bare_uris
+ascii_identifier
+tex_math_single_backslash

You can enable or disable markdown extensions using the md_extensions option (you preface an option with - to disable and + to enable it). For example:

---
title: "Habits"
output:
  html_document:
    md_extensions: -autolink_bare_uris+hard_line_breaks
---

The above would disable the autolink_bare_uris extension and enable the hard_line_breaks extension.

For more on available markdown extensions see the pandoc markdown specification.

Pandoc Arguments

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

---
title: "Habits"
output:
  ioslides_presentation:
    pandoc_args: [
      "--title-prefix", "Foo",
      "--id-prefix", "Bar"
    ]
---

Documentation on all available pandoc arguments can be found in the pandoc user guide.

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 delimeters or enclosing output object are used in this file. For example:

_output.yaml

ioslides_presentation:
  widescreen: true
  smaller: true

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