After 10 years of teaching, I have been trying to find a good presentation tool for my courses. I have experimented with a bunch of approaches, from chalkboard and whiteboard to powerpoint, keynote, beamer, etc. Every approach as its pros and cons but I have finally settled for an approach that is not too time-consuming.

What is out there?

Chalkboard and whiteboard

Pros

  • It is still my favorite method for mathematically oriented courses, that is how I feel the most comfortable because of the flexibility it gives me.
  • It forces students to write, which I still think is a key component of learning despite what some well-meaning people want me to believe.
  • It slows down the pace of the course, which I also think is a key component of learning.

Cons:

  • I end up spending a lot of time writing definitions at the board.
  • I always end up introducing a few typos, and some students are pretty unforgiving when I tell them “Just change the sign in front of $x$ throughout our calculations”.
  • Many students do not like to write anymore. I am not sure why but I am not sure we can fight this trend.
  • Many students like to have more electronic materials available, and feel more comfortable with slides.
Powerpoint and Keynote

Pros

  • That is a pretty standard tool that everyone uses, so it is easy to recycle material.
  • I can assemble a deck of slides pretty fast.
  • I can include nice illustrations and figures.

Cons

  • Most deck of slides look ugly unless I spend an unreasonable amount of time polishing them.
  • I cannot reuse anything after any unavoidable software update.
  • Including equations is a nightmare.
  • I can write on slides using a tablet, but it creates ugly and large PDFs.
  • It makes for boring lectures during which students fall asleep.
  • If I want to write details, I have to go back to the board, which is impractical when the classroom is not setup for this.
Beamer

Pros

  • I can recycle equations from my notes or papers in $\LaTeX$.

Cons

  • There is an overhead to creating a full Beamer presentations that compiles properly.
  • Basic beamer templates are ok, but my presentations look like everybody else’s.
  • Beamer eventually suffers from the same pitfalls as Powerpoint and Keynote.

What I wish for

Ideally, I would like a tool that would offer the following:

  1. It should be in a format that is easily searchable and will be supported long term.
  2. I should be able to use $\LaTeX$ equations.
  3. I should be able to write on the slides.
  4. I should be able to summon a blank slide to use as a whiteboard whenever needed.
  5. I should look relatively nice and clean.
  6. The tools should force me to focus on content without worrying too much about formatting.

What I have settled for

I have finally settled for a solution based on markdown files, which I then convert into html using pandoc, and visualize with a web browser. Slides are rendered thanks to reveal.js and mathjax javascript plugins. The result satisfies most of what I wished for, but it definitely requires a level of geekiness to use.

My workflow now boils down to the following.

  1. I create a markdown file with some basic yaml header. The markdown file supports basic formatting (sections, bold, italic), $\LaTeX$ equations, and some basic html to include figures, create definitions, etc. This is much simpler to use than beamer and I can easily search the markdown files for content.
  2. I convert the markdown file to an html file using pandoc and visualize in a web browser. The result looks clean and I can easily annotate as needed or summon a whiteboard.

A working example

Getting things installed

You will need pandoc and some javascript libraries.

  • Install pandoc from here
  • Download mathjax from here. It is possible to skip this and load the javascript from a cdn when viewing the slides, but this only works with an internet connection.
  • Download reveal.js from here.

I will assume that you have pandoc in your shell path and the following tree structure

some_directory
|-- slides
|-- mathjax
|-- reveal.js

There are a few plugins available for reveal.js, I use the following which I have found useful

  • chalkboard: a plugin adding a chalkboard and slide annotation
  • elapsed-time-bar: add progress bar of elapsed time
  • pdfexport easily switch between screen and the built-in PDF export mode by pressing a shortcut key.

Make sure that you install the plugins in some_directory/reveal.js/plugin/

some_directory
|-- slides
|-- mathjax
|-- reveal.js
	|-- [...]
	|-- plugin
		|-- [...]
		|-- chalkboard
		|-- elapsed-time-bar
		|-- pdfexport

Creating a basic css template

The layout of your slides is controlled through css. There are several templates offered by default in reveal.js, which you can easily tweak. The template we will be using is called matthieu.css. Make sure the template is in the directory some_directory/reveal.js/css/theme/

Just as an example, you can create a theorem environment as follows:

.reveal .theorem {
  display: block;
  text-align: left;
  font-style: normal;
  border-left-style: solid;
  border-left-color: orange;
  padding-left: 5px;
  border-left-width: 5px;
}
.reveal .theorem:before {
  content: "Theorem. ";
  font-weight: bold;
  color: orange;
  font-style: normal;
}
.reveal .theorem[name]:before {
  content: "Theorem (" attr(name) ") ";
}

Creating a basic html template

You also need a bunch of html formatting to properly render your slides. Fortunately, this is mostly handled by reveal.js. You only need to worry about this if you want to tweak the plugins options, add $\LaTeX$ macros to mathjax, etc. My template file is called template.md and should be stored in some_directory/slides/

some_directory
|-- slides
    |-- template.md
|-- mathjax
|-- reveal.js

Creating your first slide deck

Your slide deck is just a markdown file with basic formatting. To get started, an example file we will create myfirstslides.md in some_directory/slides/

some_directory
|-- slides
    |-- template.md
    |-- myfirstslides.md
|-- mathjax
|-- reveal.js

The first part of the file is a header with basic information

---
title: "My first slides"
author: Matthieu R Bloch
date: Tuesday, February 15, 2020
duration: 75
published: false
slideNumber: true
theme: matthieu
width: 1600
height: 1000
transition: fade
---

The meaning of the fields should be self-explanatory, with the exception of duration, which controls the length of the elapsed time bar at the bottom of the slide.

The second part of the file consists of the slides themselves.

## Slide header 1

- A first item with some equation $x^2$
- A second item with some other equation $$(a+b)^2=a^2+b^2$$

## Slide header 2

We will use a theorem

<div class="theorem" name="My first theorem">
$$1=1$$
</div>

Converting to html

Once you have your slides ready, convert them to html using the following command

pandoc -s --mathjax=../mathjax/MathJax.js -i -t revealjs myfirstslides.md
--include-in-header=leftalign.md --template=template.md -V center=false 
-V history=false -V revealjs-url=../reveal.js -o myfirstslides.html

This will create a file myfirstslides.html, which you can visualize in chrome.

some_directory
|-- slides
    |-- template.md
    |-- myfirstslides.md
    |-- myfirstslides.html
|-- mathjax
|-- reveal.js

Using and adding annotations to your slides

If you visualize your slides in chrome, you should now see something like this:

Image

You can interact with your slide deck as follows:

  • To navigate, use the keyboard arrows
  • To go full screen, press ‘F’
  • To view the side menu, press ‘M’
  • To export the presentation as a PDF file, press ‘E’ while watching the presentation. This will reformat the presentation to make it easily printable or exportable as a PDF. This is best done with Chrome, although it seems to work with Firefox and Safari.
  • To enter the slide annotation mode, press ‘C’ (for “chalkboard”)
  • To call up a blank board, press ‘B’

I have modified the template to create icons that you can click on instead of typing ‘M’, ‘C’, and ‘B’. This is convenient when using a tablet and a stylus without a physical keyboard.

All your annotations are saved in a json format. To save them, you need to download the json file by clicking on the top-most icon on the bottom left. This will simply download the json file. At the end of the lecture, change the json file name to myfirstslides.json and add it to the directory some_directory/slides/

You can now recompile your slides with the command

pandoc -s --mathjax=../mathjax/MathJax.js -i -t revealjs myfirstslides.md
--include-in-header=leftalign.md --template=template.md -V center=false -V history=false 
-V revealjs-url=../reveal.js -V loadchalkboard=myfirstslides.json

All this does is tell reveal.js to load your previous annotations through the option -V loadchalkboard=myfirstslides.json. If you reload your slides, you will have access to your annotations. If needed, you can modify what you wrote and save the result to a new json file.

some_directory
|-- slides
    |-- template.md
    |-- myfirstslides.md
    |-- myfirstslides.html
    |-- myfirstslides.json	
|-- mathjax
|-- reveal.js

Final geeky details

For those of you more inclined to investigate what is under the hood, here are a few thoughts and hacks that I have used.

Writing smoothly on a tablet

I initially had some annoying lag when writing on my tablet. I had to modify template.md following the information I found here.

Preventing download information from popping up

I save my json annotations several times during a class. To avoid chrome showing me the download information, I installed the extensions Disable Download Bar.

Adding my own LaTeX macros to mathjax

I have included a bunch of my favorite macros in template.md. Here is just a small example of what I have modified

    MathJax.Hub.Config({
      "HTML-CSS": {
          preferredFont: "TeX",
          availableFonts: ["TeX"]
      },
      TeX: {
        Macros: {
          calA: "{\\mathcal{A}}",
          calB: "{\\mathcal{B}}",
		  calC: "{\\mathcal{C}}",
          calD: "{\\mathcal{D}}",
          calK: "{\\mathcal{K}}",
          calE: "{\\mathcal{E}}",
          calF: "{\\mathcal{F}}",
          calH: "{\\mathcal{H}}",
          calL: "{\\mathcal{L}}",
          calN: "{\\mathcal{N}}",
	    }
      }
    });
Footers, headers, slide numbers

Because of how reveal.js operates, I have found it really hard to add a clean footer and to introduce slide numbers. I could get things to work in the browser but that would not export well to pdf. I have decided that it was not that crucial but that would definitely be a nice addition.

Printing PDFs

I sometimes have issues when exporting my annotations to PDFs. I ended up modifying a line 383 in the code of chalkboard.js to

if (i<storage[1].data.length -1) {
    nextSlide.push( slide.nextSibling );
}

That seems to partially solve my problem.

Last thoughts

This workflow is not perfect, but it is come as close to my wish list as I could hope. There is still a long way to make this approach a clean and user-friendly tool but it has worked pretty well for me.