Introduction to Org-Reveal

Note

As of February 2019, this fork of Org-Reveal is not maintained any longer. Please check out org-re-reveal, which continues my work and which has been accepted into MELPA.

Actually, if you are interested in my version, I suggest that you take a look at emacs-reveal, which embeds my fork, reveal.js, and useful plugins as submodules, combined with suitable Emacs configuration. A Howto for the generation of reveal.js presentations (slides with audio) with emacs-reveal exists as well.

I use emacs-reveal to generate Open Educational Resources (OER): OER presentations for a course on operating systems

Reveal.js and Org-Reveal

• Reveal.js is a tool for creating good-looking HTML presentations, authored by Hakim El Hattab.
  For an example of a reveal.js presentation, see here.
• Org-Reveal exports your Org documents to reveal.js presentations.
  With Org-reveal, you can create beautiful presentations with 3D effects from simple but powerful Org contents.

Requirements and Installation

• Reveal.js.
• Org-mode.
• ox-reveal.el.
• htmlize.el (optional, for syntax highlighting).
• And, of course, emacs.

Install Reveal.js

Download Reveal.js packages from here.

Extract Reveal.js folders from the downloaded zip file.

If you do not wish to download reveal.js yourself and would rather get a copy from a CDN, see the section Set the location of Reveal.js

Install org-reveal from MELPA

The easiest way to install org-reveal is to install package ox-reveal from MELPA.

Please refer to http://melpa.org/#/getting-started for using MELPA.

Note: It is suggested to use the Org ELPA archive in pair with the ox-reveal packages. Emacs builtin Org-mode package may be out of date for MELPA’s ox-reveal.

Install org-reveal from GitHub

You can also install the latest developing version of org-reveal directly from GitHub.

Please download the latest Org-reveal package from the Org-reveal GitHub page. Or clone the GitHub repository:

git clone https://github.com/yjwen/org-reveal.git

Copy ox-reveal.el to one of your Emacs’s load-path, and add the following statement to your .emacs file.

(require 'ox-reveal)

Note: It is suggested to use the Org-mode git repository in pair with the GitHub org-reveal. Please get the Org-mode git repository by:

$ git clone git://orgmode.org/org-mode.git

Follow the online instruction for building and installing Org-mode.

Configuration

Set the location of Reveal.js

Org-reveal must know where Reveal.js is on your computer before exporting Org contents. The location of Reveal.js is the path to the top directory of the Reveal.js packages, the directory which contains file README.md, but not the one that contains the file reveal.js.

The default location is ./reveal.js, relative to the Org file.

Changing org-reveal-root ‘s value will change the location globally. For example, add the following statement to your .emacs file:

(setq org-reveal-root "file:///d:/reveal.js")

IMPORTANT: the absolute path to Reveal.js should be in URL form, “file:///path_to_reveal.js”, as illustrated above. By setting option REVEAL_ROOT, the location is only affected within the Org file.

#+REVEAL_ROOT: file:///d:/reveal.js

Set your REVEAL_ROOT to the following URL to download reveal.js from a CDN instead of downloading a local copy.

#+REVEAL_ROOT: http://cdn.jsdelivr.net/reveal.js/3.0.0/

Url form for file location

For example if you cloned this repository to your home directory, this file in Mac OS X would be referred to as “file:///Users/username/org-reveal/readme.org”. This file in Ubuntu would be “file:///home/username/org-reveal/readme.org” and in Windows this file would be “file:///c:/Users/username/org-reveal/readme.org”. For more detail on this standard please refer to http://en.wikipedia.org/wiki/File_URI_scheme

First Try

To load Org-reveal, type “M-x load-library”, then type “ox-reveal”.

Now you can export this manual into Reveal.js presentation by typing “C-c C-e R R”.

Open the generated “Readme.html” in your browser and enjoy the cool slides.

The HLevel

Org-reveal maps each heading and its contents to one Reveal.js slide. Since Reveal.js arranges slides into a 2-dimensional matrix, Org-reveal use a HLevel value to decide whether to map headings to horizontal or vertical slides.

• Headings of level less than or equal to HLevel are mapped to horizontal slides.
• Headings with a deeper level are mapped to vertical slides.

HLevel’s default value is 1, means only level 1 headings are arranged horizontally. Deeper headings are mapped to vertical slides below their parent level 1 heading.

HLevel’s Effects on Slides Layout

Assume we have a simple Org file as below:

* H1
* H2
** H2.1
*** H2.1.1
* H3

If HLevel is 1, the default value, headings H2.1 and H2.1.1 will be mapped to vertical slides below the slides of heading H2.

If HLevel is changed to 2, slides of heading H2.1 will be changed to the main horizontal queue, and slides of heading H2.1.1 will be a vertical slide below it.

Configure HLevel’s Value

• Change variable org-reveal-hlevel’s value to set HLevel globally.
  For example, add the following statement to your .emacs file.

(setq org-reveal-hlevel 2)

• Setting Org files local HLevel to option REVEAL_HLEVEL.

#+REVEAL_HLEVEL: 2

Force Split

If one heading has too many things to fit into one slide, you can split the contents into multiple vertical slides manually, by inserting

#+REVEAL: split

Now a new slide begins after #+REVEAL keyword.

Select Theme and Transition

Themes and transition styles are set globally throughout the whole file by setting options REVEAL_THEME, REVEAL_TRANS, and REVEAL_SPEED.

For an example, please check the heading part of this document.

Available themes can be found in “css/theme/” in the reveal.js directory.

Available transitions are: default|cube|page|concave|zoom|linear|fade|none.

Set The Title Slide

By default, Org-reveal generates a title slide displaying the title, the author, the Email, the date and the time-stamp of the Org document, controlled by Org’s export settings.

To avoid a title slide, please set variable org-reveal-title-slide to nil, or add reveal_title_slide:nil to #+OPTIONS: line.

To restore the default title slide, please set variable org-reveal-title-slide to ~’auto~.

Customize the Title Slide

To customize the title slide, please set org-reveal-title-slide to a string of HTML markups. The following escape sequences can be used to retrieve document information:

%t	Title
%s	Subtitle
%a	Author
%A	Academic title
%e	Email
%d	Date
%m	Misc information
%%	Literal %

Alternatively, you can also write the title slide’s HTML code (containing the above escape sequences) into a separate file and set org-reveal-title-slide to the name of that file.

Set Slide Background

Slide background can be set to a color, an image or a repeating image array by setting heading properties.

Single Colored Background

Set property reveal_background to either an RGB color value, or any supported CSS color format.

*** Single Colored Background
   :PROPERTIES:
   :reveal_background: #123456
   :END:

Single Image Background

Set property reveal_background to an URL of background image. Set property reveal_background_trans to slide to make background image sliding rather than fading.

*** Single Image Background
    :PROPERTIES:
    :reveal_background: ./images/whale.jpg
    :reveal_background_trans: slide
    :END:

Repeating Image Background

Resize background image by setting property reveal_background_size to a number.

Set property reveal_background_repeat to repeat to repeat image on the background.

*** Repeating Image Background
    :PROPERTIES:
    :reveal_background: ./images/whale.jpg
    :reveal_background_size: 200px
    :reveal_background_repeat: repeat
    :END:

Title Slide Background Image

To set the title slide’s background image, please specify the following options:

• REVEAL_TITLE_SLIDE_BACKGROUND: A URL to the background image.
• REVEAL_TITLE_SLIDE_BACKGROUND_SIZE: HTML size specification, e.g. 200px.
• REVEAL_TITLE_SLIDE_BACKGROUND_REPEAT: set to repeat to repeat the image.

Slide Size

Reveal.js scales slides to best fit the display resolution, but you can also specify the desired size by settings the option tags width and height.

The scaling behavior can also be constrained by setting following options:

#+REVEAL_MARGIN:

a float number, the factor of empty area surrounding slide contents.

#+REVEAL_MIN_SCALE:

a float number, the minimum scaling down ratio.

#+REVEAL_MAX_SCALE:

a float number, the maximum scaling up ratio.

Slide Numbering

By default, a flatten slide number is showed at the lower-right corner of each slide.

To disable slide numbering, please add reveal_slide_number:nil to #+OPTIONS: line.

From Reveal.js 3.1.0, slide numbering can have several custom formats. To choose one format, please set reveal_slide_number to its proper string. For example, reveal_slide_number:h/v.

Supported format string can be found in Reveal.js manual.

Slide Header/Footer

Specify Slide header/footer by #+REVEAL_SLIDE_HEADER: and #+REVEAL_SLIDE_FOOTER:. The option content will be put into divisions of class slide-header and slide-footer, so you can control their appearance in custom CSS file(see Extra Stylesheets). By default header/footer content will only display on content slides. To show them also on the title and toc slide you can add reveal_global_header:t and reveal_global_footer:t to #+OPTIONS: line. To show the footer on the toc slide but not on the title slide, use option reveal_toc_footer:t.

Fragmented Contents

Make contents fragmented (show up one-by-one) by setting option ATTR_REVEAL with property “:frag frag-style”, as illustrated below.

Paragraphs can be fragmented.

• Lists can
• be fragmented.

Pictures, tables and many other HTML elements can be fragmented.

Fragment Styles

Available fragment styles are:

• grow
• shrink
• roll-in
• fade-out
• highlight-red
• highlight-green
• highlight-blue
• appear

Setting :frag t will use Reveal.js default fragment style, which can be overridden by local option #+REVEAL_DEFAULT_FRAG_STYLE or global variable org-reveal-default-frag-style.

Fragment Index

Fragment sequence can be changed by assigning adding :frag_idx property to each fragmented element.

And, this paragraph shows at last.

This paragraph shows secondly.

This paragraph shows at first.

List Fragments

#+ATTR_REVEAL: :frag frag-style above a list defines fragment style for the list as a whole.

1. All items grow.
2. As a whole.

To define fragment styles for every list item, please enumerate each item’s style in a lisp list.

none in the style list will disable fragment for the corresponding list item.

Custom fragment sequence should also be enumerated for each list item.

An example:

#+ATTR_REVEAL: :frag (grow shrink roll-in fade-out none) :frag_idx (4 3 2 1 -)
   * I will grow.
   * I will shrink.
   * I rolled in.
   * I will fade out.
   * I don't fragment.

• I will grow.
• I will shrink.
• I rolled in.
• I will fade out.
• I don’t fragment.

When there is :frag_idx specified, insufficient fragment style list will be extended by its last element. So a :frag (appear) assigns each item of a list the appear fragment style.

#+ATTR_REVEAL: :frag (appear)
   * I appear.
   * I appear.
   * I appear.

• I appear.
• I appear.
• I appear.

List Fragments with Audio

You can also use Org-Reveal in combination with the audio-slideshow plugin of reveal.js-plugins. For example, when the audio-slideshow plugin is configured properly, the following plays 1.ogg when the first list item appears, 2.ogg for the second list item, and no audio for the third. (You need to add suitable audio files to the current directory first.)

#+ATTR_REVEAL: :frag (appear) :audio (1.ogg 2.ogg none)
   * I appear with audio 1.ogg.
   * I appear with audio 2.ogg.
   * I appear without audio.

• I appear with audio 1.ogg.
• I appear with audio 2.ogg.
• I appear without audio.

Data State and Classes for Headlines and Slides, including generated ones

Set property reveal_data_state to a headline to change this slide’s display style. (In the past, reveal.min.css defined classes alert, blackout, soothe, which were activated by the data state.) In any case, property reveal_data_state adds a data-state attribute to the slide’s section element, which is called “Slide State” by reveal.js; this might also be useful with reveal.js plugins.

To add a data-state attribute to a generated title slide or table of contents slide, you can use the following options:

• REVEAL_TITLE_SLIDE_STATE
• REVEAL_TOC_SLIDE_STATE

To add a class attribute to the section element of a generated table of contents slide, you can use the option REVEAL_TOC_SLIDE_CLASS.

To add a class attribute to a slide’s h-element, add property html_headline_class to the headline.

Plug-ins

Reveal.js provides several plug-in functions.

• reveal-control : Show/hide browsing control pad.
• reveal-progress : Show/hide progress bar.
• reveal-history : Enable/disable slide history track.
• reveal-center : Enable/disable slide centering.
• multiplex : Enable audience to view presentation on secondary devices.

Configure Plug-ins

Each plugin can be toggled on/off by adding #+OPTIONS tags or by setting custom variables.

• #+OPTIONS tags:
  reveal_control, reveal_progress, reveal_history, reveal_center, reveal_rolling_links, reveal_keyboard, reveal_mousewheel, reveal_defaulttiming, reveal_overview, reveal_fragmentinurl, reveal_pdfseparatefragments, reveal_inter_presentation_links
• Custom variables:
  org-reveal-control, org-reveal-progress, org-reveal-history, org-reveal-center, org-reveal-rolling-links, org-reveal-keyboard, org-reveal-mousewheel, org-reveal-defaulttiming, org-reveal-fragmentinurl, org-reveal-pdfseparatefragments, org-reveal-overview, reveal_inter_presentation_links

For an example, please refer to the heading part of this document.

Third-Party Plugins

Reveal.js is also extensible through third-party plugins, which can be loaded with Org-Reveal. The paths to javascript loading code need to be customized in the variable org-reveal-external-plugins. This variable can be an associative list or a file. If it is an associative list the first element of each Assoc cell is a symbol – the name of the plugin – and the second is a string that will be expanded by the format function when the plugin is loaded. So, this second element should have the form: ~” {src: "%srelative/path/toplugin/from/reveal/root.js"}”~ If you need the async or callback parameters, include those too.

If org-reveal-external-plugins is a filename, that file must contain strings of the above format, one per line (without names of plugins, just the src information embedded in braces); this can also be configured within your org presentation with a line like this:

#+REVEAL_EXTERNAL_PLUGINS: external_plugins.js

In any case, Org-Reveal will add the plugins to the dependencies parameter when Reveal is initialized.

Highlight Source Code

There are two ways to highlight source code.

1. Use your Emacs theme
2. Use highlight.js

To Use your Emacs theme, please make sure htmlize.el is installed. Then no more setup is necessary.

Below is an example. Codes are copied from Haskell Wiki.

fibs = 0 : 1 : next fibs
    where next (a : t@(b:_)) = (a+b) : next t

If you saw odd indentation, please set variable org-html-indent to nil and export again.

Using highlight.js

You can also use highlight.js, by adding highlight to the Reveal.js plugin list.

#+REVEAL_PLUGINS: (highlight)

The default highlighting theme is zenburn.css brought with Reveal.js. To use other themes, please specify the CSS file name by #+REVEAL_HIGHLIGHT_CSS or the variable org-reveal-highlight-css.

The “%r” in the given CSS file name will be replaced by Reveal.js’ URL.

Editable Source Code

It is now possible to embed code blocks in a codemirror instance in order to edit code during a presentation. At present, this capacity is turned on or off at time export using these defcustoms:

• org-reveal-klipsify-src
• org-reveal-klipse-css
• org-reveal-klipse-js

This feature is turned off by default and needs to be switched on with org-reveal-klipsify-src. At present code editing is supported in javacript, clojure, php, ruby, scheme, and python only.

MathJax

${n! \over k!(n-k)!} = {n \choose k}$

LateX equation are rendered in native HTML5 contents.

IMPORTANT: Displaying equations requires internet connection to mathjax.org or local MathJax installation. For local MathJax installation, set option REVEAL_MATHJAX_URL to the URL pointing to the local MathJax location.

Note: Option reveal_mathjax is obsolete now. Org-reveal exports necessary MathJax configurations when there is Latex equation found.

Preamble and Postamble

You can define preamble and postamble contents which will not be shown as slides, but will be exported into the body part of the generated HTML file, at just before and after the slide contents.

Change preamble and postamble contents globally by setting variable org-reveal-preamble and org-reveal-postamble.

Change preamble and postamble contents locally by setting options REVEAL_PREAMBLE and REVEAL_POSTAMBLE, as illustrated at the heading part of this document.

To add custom contents into HTML <head> parts, set contents to variable org-reveal-head-preamble or option REVEAL_HEAD_PREAMBLE.

Generating Pre/Postamble by Emacs-Lisp Functions

If the contents of pre/postamble is the name of an evaluated Emacs-Lisp function, which must accept an argument of Org-mode info and return a string, the returned string will be taken as pre/postamble contents.

So you can embed the Emacs-Lisp function as an Org-Babel source block and mark it to be evaluated when exporting the document.

Raw HTML in Slides

Besides the Org contents, you can embed raw HTML contents into slides by placing a #+REVEAL_HTML keyword.

The famous cat jump fail:

Speaker Notes

Reveal.js supports speaker notes, which are displayed in a separate browser window. Pressing ‘s’ on slide’s windows will pop up a window displaying the current slide, the next slide and the speaker notes on the current slide.

Org-reveal recognize texts between #+BEGIN_NOTES and #+END_NOTES as speaker notes. See the example below.

* Heading 1
   Some contents.
#+BEGIN_NOTES
  Enter speaker notes here.
#+END_NOTES

Speaker notes requires the notes plug-in. If you changed default plug-in setting by specifying #+REVEAL_PLUGINS or by setting variable org-reveal-plugins, please make sure notes is in the plug-in list to enable speaker notes.

Due to a bug in Reveal.js, sometimes the speaker notes window shows only blank screens. A workaround to this issue is to put the presentation HTML file into the Reveal.js root directory and reopen it in the browser.

Easy-Template for Speaker Notes

Org-reveal registers ‘n’ as the key for speaker notes easy-template. So you can press ‘<’ followed by ‘n’ and then press TAB, the #+BEGIN_NOTES and #+END_NOTES pair is inserted automatically.

Customize org-reveal-note-key-char to change the default key ‘n’. set it to nil will forbid the auto-completion for speaker notes.

Multiplexing

Reveal.js supports multiplexing, which allows allows your audience to view the slides of the presentation you are controlling on their own phone, tablet or laptop. As the master presentation navigates the slides, all client presentations will update in real time. See a demo at http://revealjs.jit.su/.

You can enable multiplexing for your slide generation by including the following options:

#+REVEAL_MULTIPLEX_ID: [Obtained from the socket.io server. ]
#+REVEAL_MULTIPLEX_SECRET: [Obtained from socket.io server. Gives the master control of the presentation.]
#+REVEAL_MULTIPLEX_URL: http://revealjs.jit.su:80 [Location of socket.io server]
#+REVEAL_MULTIPLEX_SOCKETIO_URL: http://cdnjs.cloudflare.com/ajax/libs/socket.io/0.9.10/socket.io.min.js
#+REVEAL_PLUGINS: ([any other plugins you are using] multiplex)

You must generate unique values for the REVEAL_MULTIPLEX_ID and REVEAL_MULTIPLEX_SECRET options, obtaining these from the socket.io server you are using.

If you include these options in your .org file, reveal-org will enable your .html file as the master file for multiplexing and will generate a file named in the form [filename]_client.html in the same directory as the client .html file. Provide your audience with a link to the client file to allow them to track your presentation on their own device.

Extra Stylesheets

Set REVEAL_EXTRA_CSS to a stylesheet file path in order to load extra custom styles after loading a theme.

#+REVEAL_EXTRA_CSS: url-to-custom-stylesheet.css

Select Built-In Scripts

Set option REVEAL_PLUGINS or variable org-reveal-plugins to a lisp list to select built-in scripts.

Available built-in scripts are: classList/markdown/highlight/zoom/notes/search/remotes.

Default built-ins are: classList/markdown/highlight/zoom/notes/multiplex.

The following examples select markdown and highlight only.

#+REVEAL_PLUGINS: (markdown highlight)

Extra Dependent Script

Set REVEAL_EXTRA_JS to the url of extra reveal.js dependent script if necessary.

#+REVEAL_EXTRA_JS: url-to-custom-script.js

Extra Slide Attribute

Set property reveal_extra_attr to headings to add any necessary attributes to slides.

Export into Single File

By setting option reveal_single_file to t, images and basic Reveal.js scripts will be embedded into the exported HTML file, to make a portable HTML. Please note that remote images will not be included in the single file, so presentations with remote images will still require an Internet connection.

Attention: This needs locally available reveal.js files!

#+OPTIONS: reveal_single_file:t

Limitations of single file export

• Some functions provided by Reveal.js libraries will be disabled, including PDF export, Markdown support, zooming, speaker notes, and remote control.
  • Code highlighting by highlight.js is also disabled, but code highlighting by Emacs is not affected.
• Plugins are not enabled.
• CSS needs to be self-contained. Neither @import rules nor other forms of URLs work (images need to be embedded as data URIs).
• If you use org-reveal-title-slide with custom HTML code and images, you need to embed images in the form of data URIs yourself.

Export Current Subtree

Use menu entry ” C-c C-e R S” to export only current subtree, without the title slide and the table of content, for a quick preview of your current edition.

Tips

Disable Heading Numbers

Add num:nil to #+OPTIONS

#+OPTIONS: num:nil

Disable Table of Contents

Add toc:nil to #+OPTIONS

#+OPTIONS: toc:nil

This is actually an option recognized by org-export. It is only mentioned here because slide decks often do not need a TOC.

Internal Links

Reveal.js supports only jump between slides, but not between elements on slides. Thus, we can only link to headlines in an Org document.

You can create links pointing to a headline’s text, or its custom-id, as the examples below:

• Tips.
• Heading with a CUSTOM_ID property.

If you add reveal_inter_presentation_links:t to #+OPTIONS, such links also work between presentations on the same server, e.g., [[file:somefile.org::#anchor][link text]].

Reveal.js advertises to use broken internal links, which are used in Org-Reveal by default. (Those links work with reveal.js, but are not understood by search engines.) If you change org-reveal--href-fragment-prefix from its default to the value of org-reveal--slide-id-prefix, valid links are generated:

(setq org-reveal--href-fragment-prefix org-reveal--slide-id-prefix)

Whether this change is a good idea might be discussed under this reveal.js issue.

Custom JS

To pass custom JS code to Reveal.initialize, state the code by #+REVEAL_INIT_SCRIPT (multiple statements are concatenated) or by custom variable org-reveal-init-script.

Executable Source Blocks

To allow live execution of code in some languages, enable the klipse plugin by setting org-reveal-klipsify-src to non-nil. Src blocks with the languages js, clojure, html, python, ruby, scheme, php will be executed with output shown in a console-like environment. See the source code of org-reveal-src-block for more details.

HTML Src Block

<h1 class="whatever">hello, what's your name</h1>

Javascript Src Block

console.log("success");
var x='string using single quote';
x

Perl Src Block (not klipsified)

I don't know perl!

Thanks

Courtesy to:

The powerful Org-mode,

the impressive Reveal.js

and the precise MathJax