Beamer presentations using the new export engine

Table of Contents


This tutorial covers exporting org documents to LaTeX Beamer slides using the new export engine, org-elements and ox (short for org-export), written by Nicolas Goaziou.

Note: It will not cover any of the basic features common with the old beamer exporter; it will only focus on the improvements, new additions and backwards incompatibilities. It is also assumed that the reader is already acquainted with GNU Emacs and Org mode itself. Basic understanding of LaTeX and the Beamer package is also assumed.

Initial setup

Unlike the old exporter, requiring the beamer exporter is not enough to export to beamer slides with ox. This difference arises from a new feature in ox-beamer that allows, in the author's words, a beamer translation of any org document. This is extremely useful when creating handouts or article versions of your slides by loading the beamerarticle package (see the beamer user guide for specifics).

You can use the following minimal setup to start exporting to the beamer documentclass. As of the latest Org mode version (8.0.3), this setup is not necessary anymore. If you want to customise this variable, you should do it before loading ox-beamer.

(require 'ox-latex)
(add-to-list 'org-latex-classes
               ("\\section\{%s\}" . "\\section*\{%s\}")
               ("\\subsection\{%s\}" . "\\subsection*\{%s\}")
               ("\\subsubsection\{%s\}" . "\\subsubsection*\{%s\}")))

The first string beamer in org-latex-classes is by no means unique, it can be substituted for any convenient name you wish. This name however should be the argument to the LaTeX_CLASS file header option (or EXPORT_LaTeX_CLASS subtree property).

Eric recently updated the old example presentation for beamer export to work with ox-beamer. You can take a look at that to get started.

Configuring export options

Apart from the usual export options provided by the OPTIONS keyword, you can put additional beamer export options in the file header. For a minimal beamer export, you have to specify the LaTeX_CLASS and the LaTeX_CLASS_OPTIONS keywords in the header of a file. A preset export template can be inserted by calling the interactive function org-beamer-insert-options-template. This can be further modified as per your needs. You can also do a subtree export; in that case you can provide the keywords as subtree PROPERTIES. However take note that the keyword names should be prepended with EXPORT_. A list of supported keywords are,

Table 1: Export option keywords and corresponding subtree properties.
File header keywords Subtree properties

For a subtree export, a few extra keywords are supported. For example you can specify the exported filename with the EXPORT_FILE_NAME property.

Table 2: Properties specific to subtree export
Subtree properties Functionality
EXPORT_TITLE Export title
EXPORT_AUTHOR Export author
EXPORT_DATE Export date
EXPORT_FILE_NAME Export file name

A simple example

A simple file header might look like the example below.

#+LaTeX_CLASS: beamer
#+LaTeX_CLASS_OPTIONS: [presentation,smaller]
#+BEAMER_THEME: default

A corresponding subtree export should have properties as shown below.

* Exported title
  :EXPORT_LaTeX_CLASS: beamer
  :EXPORT_LaTeX_CLASS_OPTIONS: [presentation,smaller]
  :EXPORT_FILE_NAME: presentation.pdf

The export class, as defined in org-latex-classes, determines the documentclass, and the class options are passed on as optional arguments (note the presence of square brackets).


Configuring frame export level

The new exporter allows the grouping slides into LaTeX sections. The sectioning behaviour is controlled by org-latex-classes, where as heading levels to be exported as frames are controlled by the H:n option to the OPTIONS keyword (EXPORT_OPTIONS property for subtree export). The n here is the headline level number that you want to export as frames. To elaborate with an example, to export third level headlines as frames, use #+OPTIONS: H:3 in the file header. This behaviour can be overridden per headline by setting the BEAMER_env property to frame. You can also provide options to a frame by setting the BEAMER_opt property on the headline. This also adds the fragile option to the frame.

Use of filters to customise export

ox also gives you access to all org-element entities in the exported text for customisation with user filters. Filters are essentially simple lisp functions that reformat the exported elements. As a simple example; the ox-beamer translates bold text as \alert{bold text}. To revert this back to the old behaviour, you can you a filter like this:

(defun my-beamer-bold (contents backend info)
  (when (eq backend 'beamer)
    (replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\textbf" contents)))

(add-to-list 'org-export-filter-bold-functions 'my-beamer-bold)

Another example would be to translate strike through text to \structure{strike through text} with the following filter.

(defun my-beamer-structure (contents backend info)
  (when (eq backend 'beamer)
    (replace-regexp-in-string "\\`\\\\[A-Za-z0-9]+" "\\\\structure" contents)))

(add-to-list 'org-export-filter-strike-through-functions 'my-beamer-structure)

Structure editing, environments and markup

All the usual Org mode structure editing commands work. The minor mode org-beamer-mode is also provided to make it convenient to insert Beamer specific environments in an org-mode buffer.

A notable change in ox-beamer with regards to markup is, bold text is translated as \alert{bold text} by default.

Block environments and overlay specifications

All headlines below the org-beamer-frame-level (i.e. below H value in OPTIONS), are exported as blocks with ox-beamer. You can choose special block environments by setting the BEAMER_env property on the headline. Supported blocks are listed in org-beamer-environments-default. To specify an overlay specification for a frame or block environment, set the BEAMER_act property. If the value is enclosed in square brackets, it is interpreted as a default overlay specification.

* A theorem block
  :BEAMER_env: theorem
  :BEAMER_act: <2->

The =BEAMER_act= property says to overlay this environment from the
second frame onwards.

You can add your own environments by customising the org-beamer-environments-extra variable. For example the snippet below adds support for only environment and associates to the letter O.

(add-to-list 'org-beamer-environments-extra
             '("onlyenv" "O" "\\begin{onlyenv}%a" "\\end{onlyenv}"))

Special enviroments

Environments can be put in a column by setting the BEAMER_col property on a headline. It accepts decimal point numbers which is interpreted as a fraction of the text width. If the beadline does not have an enviroment the headline text is ignored and all the contents are put inside the column environment.

* A block in a column
  :BEAMER_env: block
  :BEAMER_col: 0.5

* Just a column with contents
  :BEAMER_col: 0.5
Some text, the headline above is ignored

You can start an appendix by setting the BEAMER_env property to appendix on a headline. Similarly you can insert notes by setting the property to note (use noteNH to exclude the headline from the note). You can also use Beamer's againframe command by setting the same property. The frame being refered to by againframe is specified by the BEAMER_ref property. You can also ignore a headline by using ignoreheading. This can also be used to close a column environment.

All contiguous environments are automatically wrapped in a columns environment, although it can be forced at any point by setting the BEAMER_env property to columns. This might be handy if you want to pass special options.

Migrating from the old to the new exporter


Many configuration variables have been renamed, some might even have slightly different meanings. For a summary of these changes take a look at the following entries:

If there is information missing from the above entries, please do not hesitate to report on the Org mode mailing list.

Besides configuration variables, the earlier version allowed more generic configuration of export using hooks. This has been replaced by export filters. There is a nice article on how you could explore available filters by Charles Berry. A few simple examples were also shown above.

That said, two old-style hooks are still available: org-export-before-parsing-hook, and org-export-before-processing-hook. Take a look at their documentation strings for more details.

Backwards incompatible changes

The new exporter has a few backwards incompatible changes. The most visible change is the export behaviour of headlines deeper than the exported headline level. You can configure the headline levels that are exported with the #+OPTIONS: H:n line (as explained earlier). If there are any headlines deeper than n, they are exported as blocks during beamer export. For the old exporter, these were exported as unordered lists. This thread from the mailing list archive has some discussion on how to deal with this change. If you have anything to add to that discussion, please share on the mailing list.

New features available with the new exporter

TODO Hacks

Show some non-trivial hacks that can be used to achieve customised output. Often one needs to do these when trying to work with beamer specific features like overlay. One example:

TODO Beamer article

Discuss that EXPORT_LaTeX_CLASS need not be beamer. Useful to export beamerarticle document for slides.

Email from Nicolas Goaziou discussing this feature:

TODO Snippet translation

TODO Ordered and unordered lists

TODO Images

TODO Tables

TODO Source blocks

DONE Environments

TODO Examples

  1. [ ] Sectioning and TOC (progress state between sections)
  2. [ ] Overlays
  3. [ ] Blocks
    1. [ ] Normal blocks
    2. [ ] Verbatim blocks
    3. [ ] Source blocks
  4. [X] Columns
  5. [ ] Text / LaTeX commands in between frames
  6. [ ] Images
    • Centering
    • Captions
  7. [ ] Footnotes and references
  8. [X] Backup slides with \appendix
  9. [ ] Caveats about using alternate TeX binaries

Documentation from the website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.