Introduction to Org-Reveal

Reveal.js and Org-Reveal

Reveal.js is a tool for creating good-looking HTML presentations. See https://github.com/hakimel/reveal.js/.
For an example of reveal.js presentation, click 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.

Repository

This repository is modified from Yujie Wen’s repo (thanks!)

Besides some minor code formating, the changes include:

changed some variable settings. Some variables are removed from global customization.
removed reveal_postamble and reveal_preamble. It seems useless to me and reveal.js does not handle them very well.
added functionality to set attributes for the title slide.
added functions to handle footnote export.
added shorcut to insert speaker notes.
changed original mathjax related code for utilizing the mathjax code in ox-html.el. This has 2 advantages:
1. reduce code redundancy
2. the same document can be exported both to html or reveal.js without changes
other minor changes.

Requirements and Installation

Reveal.js.
Latest org-mode.
ox-reveal.el.
And, of course, emacs.

Obtain Reveal.js

Download Reveal.js packages from here.
Extract Reveal.js folders from the downloaded zip file.
If you do not wish you download reveal.js and want to use a CDN version, see the section Set the location of Reveal.js

Obtain org-mode

Org-reveal relies on the Org-mode export frame work. Pre-packaged org-mode may be out-of-date has not been tested.
If not sure, use the latest development codes from git repository.
You can install it in Emacs with M-x package-install and then type org.

Or get it from github:
```
git clone git://orgmode.org/org-mode.git
    
```
Then Follow the online instruction to build and install Org-mode.

Obtain Org-reveal

Download 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 the Org-mode installation directory.
Add the following statement to your .emacs file.
```
(require 'ox-reveal)
    
```

Configuration and Usage

You can export this file with C-c C-e R R to see the effects of following config. Before that, make sure the path settings at the head of the file is right for you.

Press s to show speaker notes
Press ESC to enter the slide overview.
Hold down Alt and click on any element to zoom in on it using zoom.js. Alt + click anywhere to zoom back out.
Press b or . on your keyboard to enter the ‘paused’ mode. This mode is helpful when you want to take distracting slides off the screen during a presentation.

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 Reveal.js packages, the one which contains file README.md, but not the one contains file reveal.js.

The default location is current directory of the org file.

Change the value of variable org-reveal-root will change the location globally. For example, add the following statement to your .emacs file:

(setq org-reveal-root "/Users/zech/Dropbox/git/reveal.js")

By setting option REVEAL_ROOT, the location is only affected within the Org file.

#+REVEAL_ROOT: /Users/zech/Dropbox/git/reveal.js

First Try

To wake-up Org-reveal now, 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 slides. Since Reveal.js arranges slides into a 2-dimentional matrix, Org-reveal use a HLevel value to decide map headings to hozirontal or vertical slides.

Headings of level less or equal to HLevel are mapped to hozirontal slides.
Headings of deeper levels 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 its 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 mapping to vertical slides below the slides of heading H2.

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

Configure HLevel’s Value

Setting Org files local HLevel using #+OPTIONS tag reveal_hlevel.
```
	#+OPTIONS: reveal_hlevel:2
    
```

Force Split

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

#+REVEAL_HTML: SPLIT

Now a new slide begins after #+REVEAL_HTML: SPLIT keyword.

Select Theme and Transition Style and Speed

Themes and transition styles are set globally throughout the whole file by setting options REVEAL_THEME, REVEAL_TRANS, and REVEAL_SPEED in your org-mode file.

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

Please check reveal.js documentation for available themes and transition styles.

Slide Size

Reveal.js scales slides to best fit the display resolution. But in case the auto-sizes are not satisfiable, you can specify the desired size by #+OPTIONS tag reveal_width and reveal_height.

The scaling behavior can also be contrainted by setting following #+OPTIONS tags:

reveal_margin a float number, the factor of empty area surrounding slide contents.
reveal_min_scale a float number, the minimun scaling down ratio.
reveal_max_scale a float number, the maximum scaling up ratio.

Slide Numbering

Enabled by default. To deactivate slide numbers:

#+OPTIONS: reveal_slide_number:nil

Slide of outline

The following setting only shows the outermost headline.

#+OPTIONS: toc:1

You can disable it with:

#+OPTIONS: toc:nil

Disable Heading Numbers

To remove the section numbers on titles of slides (default):

#+OPTIONS: num:nil

Set low-level headlines as list rather than slides

If you set like following, all headlines lower than level 3 will be exported as list item instead of stand alone slides.

#+OPTIONS: H:3

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.

Items can be fragmented, too.

Availabe fragment styles are:

grow

shrink

roll-in

fade-out

highlight-red

highlight-green

highlight-blue

Set Individual 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_data_bg to either an RGB color value, or any supported CSS color format.

   *** Single Colored Background
	  :PROPERTIES:
	  :reveal_data_bg: #543210
	  :END:

Single Image Background

Set property reveal_data_bg to an URL of background image. Set property reveal_data_bg_trans to slide to make background image sliding rather than fading.

   *** Single Image Background
	:PROPERTIES:
	:reveal_data_bg: images/whale.jpg
	:reveal_data_bg_trans: slide
	:END:

Repeating Image Background

Resize background image by setting property reveal_data_bg_size to a number.

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

   *** Repeating Image Background
	:PROPERTIES:
	:reveal_data_bg: images/whale.jpg
	:reveal_data_bg_size: 400px
	:reveal_data_bg_repeat: repeat
	:END:

Set Extra Individual Slide Attribute

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

For example, you can use it to set the background color and the size of the text - such as this very slide.

Set Data State for Individual Slide

Set property reveal_data_state to headings to change this slide’s display style, as illustrated here:

    ** Data State
	:PROPERTIES:
	:reveal_data_state: custemevent
	:END:

~~Availabe data states are: =alert=, =blackout=, =soothe=.~~

Footnote

Footnote can be defined and exported to each slide. Inline footnote is recommended.

For example, org-mode is awesome project [fn:: http://orgmode.org/] and org-reveal is awesome [fn:: https://github.com/yjwen/org-reveal & https://github.com/RNAer/org-reveal] too.

This is great for listing citations on the slide.

Source Codes

Org-reveal use Org-Babel to highlight source codes.

>>> if x < 0:
...     x = 0
...     print 'Negative changed to zero'
... elif x == 0:
...     print 'Zero'
... elif x == 1:
...     print 'Single'
... else:
...     print 'More'

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

MathJax

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

Latex equation are renderred in native HTML5 contents.

IMPORTANT: Displaying equations requires internet connection to mathjax.org or local MathJax installation.

IMPORTANT: For local MathJax installation, set option HTML_MATHJAX to locate the URL pointing to the local MathJax location. Search org-mode documentation for details.

You can set #+OPTIONS tag reveal_mathjax to nil to disable the mathjax rendering.

Raw HTML in Slides

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

Now break time, watch two videos:

or embed a webpage inside a slide:

Speaker Notes

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

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

You can type <n and then TAB to insert empty note block.

   * Heading 1
     Some contents.
     #+BEGIN_NOTES
	Enter speaker notes here.
     #+END_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 brower.

It is recommended to download reveal.js and run grunt server locally for this. See reveal.js documentation for details.

Extra Stylesheets and Javascripts

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

Similarly, set REVEAL_EXTRA_JS to the url of extra reveal.js dependent script if necessary:

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

Internal Links - jumping between slides

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

jump to Speaker Notes: currently links to headline text does work properly.
jump to MathJax: link to the headings with the specified CUSTOM_ID property.

Org Table

An example of how a table is exported in org-reveal:

ID	OTU1	OTU2
1	30	2
2	0	70

Checkbox on Org List

An example of how checkbox before org list exported:

[X] book A
[ ] book B

To-do

aware of ::
currently change fragment style between list items will break the whole list into smaller list and then break the consistent style.

Acknowledgment

Courtesy to:

The powerful Org-mode,
the impressive Reveal.js,
and the precise MathJax

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
images		images
.gitignore		.gitignore
ox-reveal.el		ox-reveal.el
readme.html		readme.html
readme.org		readme.org

Folders and files

Latest commit

History

Repository files navigation