Lecture Notes

version 2.0, fall 2020

Here's my current solution for doing integrated slides and lecture notes using Pandoc and Markdown.

To use

1. Put pandoc-slides, pandoc-handout-filter.lua, and pandoc-*.tex somewhere in your PATH.

2. You must open pandoc-slides and edit the five paths to those supplementary files to indicate where you put them. (By default, these reference ./ so that the example in the repository will build.)

3. Write a lecture in the rough format of Lecture.md. Title, author, and date from the YAML front-matter work the way you'd expect. Everything else will be configured automatically. The notes should appear inside a <div class="notes"> tag, and can use full Markdown formatting as well.

How do I configure it more?

There's a number of things you can easily configure, and then a bunch of progressively more interesting and challenging tweaks:

• In the pandoc-slides script, you will see a variety of different Pandoc variables that can be used to configure your output:

  • -V theme=Pittsburgh --- set the general Beamer theme that you would like your slides to use
  • -V fonttheme=structurebold --- set the beamer font theme that you would like your slides to use
  • -V fontfamily=opensans --- set to the name of a TeX package that loads the main font you would like to use for your slides
  • -V fontfamilyoptions=defaultsans --- a string that will be passed as the package options to your font package (i.e., the default settings are to call \usepackage[defaultsans]{opensans})
  • -V papersize=a4 --- set the paper size for the lecture notes
  • -V geometry=... --- set the margins for the lecture notes
  • -V fontfamily=mathptmx --- set to the name of a TeX package that lods the main font that you would like your lecture notes to use

• If you have a separate folder in which you keep a central collection of slide images that you would like all of your slides and handouts to reference, you can add:

  --resource-path .:/path/to/your/images

  to both the commands for slides and handout generation, and Pandoc will automatically search for the rest of your image files.

• For further customization, you can add whatever you want to the pandoc-*-snippet.tex files. The beamer file is loaded by both slides and handouts, and the others by only one of the two respectively.

• If you use zsh, you can add compdef '_files -g "*.md"' pandoc-slides to your .zshrc to make completion work for .md files after you type pandoc-slides.

What do you get?

You get some relatively nicely formatted Beamer slides, along with a lecture notes file that interleaves your notes with a basic text version of your slide content.

What does it look like?

Check out the two PDFs here for examples.

How does it work?

• The pandoc-filter.lua file, which is only added for the handout files, wraps the notes content in a \begin{slidenotes} environment.
• The pandoc-beamer-snippet.tex file disables figure numbering in both handouts and in slides.
• The pandoc-slides-snippet.tex file can be used to add all sorts of slide styling. Per default, it sets some nice defaults for block quotations, cleans up the formatting of figures, and turns off the slide navigation symbols.
• The pandoc-handout-snippet.tex file adds some nice styling to the notes sections, as well as disabling the printing of graphics in the handouts.

What's new in this version?

The old version of these hacks involved overwriting the Pandoc internal Beamer or TeX templates. This is a dangerous thing to do, as those templates are sometimes updated internally by Pandoc, which will then expect them to contain things that your version of the template doesn't have. I strongly recommend using include-snippets and Lua filters, as I've done here, to modify the files generated after the fact rather than overriding the template.

Can I steal it?

Yup. This work is licensed under Creative Commons CC0 1.0 Universal.