Title links are for viewing within org-mode buffer only. Github viewers please use the =(gh)= links.
- Initialization options(gh)
- Third-Party Plugins(gh)
- Highlight Source Code(gh)
- Auto-Animate (gh)
- Editable Source Code(gh)
- MathJax(gh)
- Preamble and Postamble(gh)
- Raw HTML in Slides(gh)
- Speaker Notes(gh)
- Multiplexing(gh)
- Extra Stylesheets and Script Sources(gh)
- Select Built-In Scripts(gh)
- Extra Dependent Script(gh)
- Extra Slide Attribute(gh)
- Export into Single File(gh)
- Export Current Subtree(gh)
- 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.
- Reveal.js.
- Org-mode.
- ox-reveal.el.
- htmlize.el (optional, for syntax highlighting).
- And, of course, emacs.
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
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.
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 https://code.orgmode.org/bzg/org-mode
Follow the online instruction for building and installing Org-mode.
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: https://cdn.jsdelivr.net/npm/reveal.js
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
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.
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.
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.
- 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
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.
To repeat the heading title on the split slide, please insert
#+REVEAL: split:t
instead.
Theme is set globally throughout the whole file by setting option
REVEAL_THEME
.
Slide transition style is set by initialization option transition
and the transition speed is set by transitionSpeed
. Please refer to
section Initialization options for details.
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.
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
.
There are 3 ways to customize the title slide.
- Set variable
org-reveal-title-slide
to a string of HTML markups. - Set
reveal_title_slide
in the#+OPTIONS:
line to a string of HTML markups. - Use one or more option lines
#+REVEAL_TITLE_SLIDE:
to specify the HTML of the title slide.
The following escaping characters can be used to retrieve document information:
%t | Title |
%s | Subtitle |
%a | Author |
%e | |
%d | Date |
%% | Literal % |
Using this option allows to thoroughly change the style of the title slide:
REVEAL_TITLE_SLIDE_STATE
: Style applied to the viewport of title slide. See the reveal.js documentation for details.
Slide background can be set to a color, an image, a repeating image array or an iframe by setting heading properties.
Set property reveal_background
to either an RGB color value, or any
supported CSS color format.
*** Single Colored Background
:PROPERTIES:
:reveal_background: #123456
:END:
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:
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, reveal_background_opacity
for the
background opacity, which is a value of 0-1.
*** Repeating Image Background
:PROPERTIES:
:reveal_background: ./images/whale.jpg
:reveal_background_size: 200px
:reveal_background_repeat: repeat
:reveal_background_opacity: 0.2
:END:
When iframe
is being used as slide background, the content of the slide will
be put inside a dedicated division. The other background options can be used to
configure this new division. The reveal_background
supports both color and
image as a normal slide.
:PROPERTIES:
:reveal_background_iframe: https://hakim.se
:reveal_background: rgb(0,0,0)
:reveal_background_opacity: 0.8
:END:
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 torepeat
to repeat the image.REVEAL_TITLE_SLIDE_BACKGROUND_OPACITY
: Set the background opacity.
To set the (automatically generated) table of contents slide’s background image, please specify the following options:
REVEAL_TOC_SLIDE_BACKGROUND
: A URL to the background image.REVEAL_TOC_SLIDE_BACKGROUND_SIZE
: HTML size specification, e.g.200px
.REVEAL_TOC_SLIDE_BACKGROUND_REPEAT
: Set torepeat
to repeat the image.REVEAL_TOC_SLIDE_BACKGROUND_OPACITY
: Set the background opacity.
You can also configure the background for all slides in the presentation with:
REVEAL_DEFAULT_SLIDE_BACKGROUND
REVEAL_DEFAULT_SLIDE_BACKGROUND_SIZE
REVEAL_DEFAULT_SLIDE_BACKGROUND_POSITION
REVEAL_DEFAULT_SLIDE_BACKGROUND_REPEAT
REVEAL_DEFAULT_SLIDE_BACKGROUND_TRANSITION
Refer to the Set slide background section for instructions on how to use each parameter.
Reveal.js scales slides to best fit the display resolution, but you can
also specify the desired size by settings the option tags reveal_width
and reveal_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.
To enable slide numbers, please add the following Reveal.js initial option.
#+REVEAL_INIT_OPTIONS: slideNumber:true
Other possible choice for slide numbers are:
“h.v” | Horizontal . vertical slide number. The same as true |
“h/v” | Horizontal / vertical slide number |
“c” | Flatten slide number |
“c/t” | Flatten slide number / total slides |
Specify Slide header/footer globally 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.
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.
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 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.
#+ATTR_REVEAL: :frag frag-style
above a list defines fragment
style for the list as a whole.
- All items grow.
- 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.
Use #+REVEAL_INIT_OPTIONS
to give JS snippet for initialize
reveal.js with different options. Check reveal.js document for
supported options. Check the head part of this document for an
example.
Reveal.js is also extensible through third-party plugins. Org-reveal
provides a customizable variable org-reveal-external-plugins
for
defining available third-party plugins. This variable is an
associative list. The first element of each Assoc cell is a symbol
same as the name of the plugin and the second is either a string
specifying the location of the plugin script or a list of string in
case of multiple scripts. Each script string can have ONE optional
%s
, which will be replaced by `reveal-root`. Code below is an
example.
(setq org-reveal-external-plugins '((RevealMenu . "path/to/reveal.js-menu/menu.js"))
Plugins can be specified in buffer by one or more
#+REVEAL_EXTERNAL_PLUGINS
options. Each option can have one or more
plugin specifications of the same format as in
org-reveal-external-plugins
. Below is an example.
#+REVEAL_EXTERNAL_PLUGINS: (plugin1 . "ex/plugin1.js") (plugin2 . "ex/plugin2.js")
#+REVEAL_EXTERNAL_PLUGINS: (plugin3 "ex/plugin3-1.js" "ex/plugin3-2.js")
At most one %s
can be inserted into each plugin string, which will
be replaced by Reveal.js root path.
There are two ways to highlight source code.
- Use your Emacs theme
- 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 of highlighted lisp code from org-reveal.
(defun org-reveal--read-file (file)
"Return the content of file"
(with-temp-buffer
(insert-file-contents-literally file)
(buffer-string)))
If you saw odd indentation, please set variable org-html-indent
to nil
and export again.
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.
Reveal.js supports to enable line numbers and highlighting on
given line numbers. Please use :code_attribs
to pass the proper
attributes to the source code block . Below is an example.
#+ATTR_REVEAL: :code_attribs data-line-numbers='1|3'
#+BEGIN_SRC c++
int main()
{
cout << "Hello" << endl;
}
#+END_SRC
To enable auto-animate, please add data-auto-animate
to heading’s
REVEAL_EXTRA_ATTR
property. To force Reveal.js to match source
codes across slides, please add the same :data_id foo
to the
#+ADDR_REVEAL:
tag of the source code blocks. Example as below.
* Heading 1
:PROPERTIES:
:REVEAL_EXTRA_ATTR: data-auto-animate
:END:
#+ATTR_REVEAL: :data_id foo
#+begin_src js
let index = 1
#+end_src
* Heading 2
:PROPERTIES:
:REVEAL_EXTRA_ATTR: data-auto-animate
:END:
#+ATTR_REVEAL: :data_id foo
#+begin_src js
let index = 1
let value = 2
#+end_src
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 javascript, clojure, php, ruby, scheme, and python only.
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.
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
.
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.
Besides the Org contents, you can embed raw HTML contents
into slides by placing a #+REVEAL_HTML
keyword.
The famous cat jump fail:
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
To skip exporting speaker notes, please set variable
org-reveal-ignore-speaker-notes
to t
.
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.
Reveal.js supports a multiplexing plugin, which 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 https://reveal-multiplex.glitch.me/.
To use multiplexing, first prepare a Socket.io server by the
instruction here. Then include the following options in the org
file. Contents in []
are commentary notes, not part of the
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: https://reveal-multiplex.glitch.me [Location of socket.io server]
#+REVEAL_PLUGINS: ([any other plugins you are using] multiplex)
If your are using Reveal.js 3.x, an extra option is necessary for Socket.io scripts.
#+REVEAL_MULTIPLEX_SOCKETIO_URL: http://cdnjs.cloudflare.com/ajax/libs/socket.io/0.9.10/socket.io.min.js
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.
Set REVEAL_EXTRA_CSS
to a stylesheet file path to load extra
custom styles after loading a theme.
Set REVEAL_EXTRA_SCRIPT_SRC
to script file path to load extra
script sources. In case of multiple script files, specify each of
them by one REVEAL_EXTRA_SCRIPT_SRC
line. The specified scripts
is loaded after Reveal.js initialization.
Scripts that must be loaded before Reveal.js initialization can be
set by one or more REVEAL_EXTRA_SCRIPT_BEFORE_SRC
lines.
#+REVEAL_EXTRA_CSS: url-to-custom-stylesheet.css
#+REVEAL_EXTRA_SCRIPT_SRC: url-to-custom-script
Same setup can be done globally by customize variables
org-reveal-extra-css
, org-reveal-extra-script-src
and
org-reveal-extra-script-before-src
. In case of multiple script
files, organize the script file names as a list.
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)
Set REVEAL_EXTRA_JS
to the url of extra reveal.js dependent
script if necessary.
#+REVEAL_EXTRA_JS: url-to-custom-script.js
Set property reveal_extra_attr
to headings to add any necessary attributes
to slides.
By setting option reveal_single_file
to t
, images and necessary
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
When exporting into single file, functions provided by Reveal.js libraries will be disabled due to limitation, including PDF export, Markdown support, zooming, speaker notes and remote control.
Code highlight by highlight.js is also disabled. But code highlight by Emacs is not effected.
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.
Any heading with tag :noexport:
will be discarded when exporting to
all backends. If you want a heading being discard when exporting to
Reveal.js only, please use tag :noexport_reveal:
.
It is well often the automatic “Table of Contents” is too large to fit
into one slide. One workaround is to disable the automatic TOC and
generate one manually, which can be split into multiple
slides. Org-reveal provides a helper function to insert a TOC to the
current org buffer. Type M-x org-reveal-manual-toc
to invoke it.
To disable the automatic TOC, add toc:nil
to #+OPTIONS
#+OPTIONS: toc:nil
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:
To pass custom JS code to Reveal.initialize
, state the code by
#+REVEAL_EXTRA_INITIAL_JS
(multiple statements are concatenated)
or by custom variable org-reveal-extra-initial-js
. The first
appearance of %s
in the script will be replaced by Reveal.js root path.
If you want to add extra code outside of the Reveal.initialize
block, then #+REVEAL_EXTRA_SCRIPT
can be used. The code will be
inserted after closing the Reveal.initialize
statement, but before
the closing </script>
tag.
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.
<h1 class="whatever">hello, what's your name</h1>
console.log("success");
var x='string using single quote';
x
I don't know perl!
If you want to have multiple reveal presentations in a single Org-mode file, you might want to switch from file-based properties like:
#+REVEAL_HLEVEL: 2
#+REVEAL_INIT_OPTIONS: transition: 'cube'
#+REVEAL_THEME: moon
to properties of sub-headings like:
:PROPERTIES:
:EXPORT_REVEAL_HLEVEL: 2
:EXPORT_INIT_OPTIONS: transition: 'cube'
:EXPORT_REVEAL_THEME: moon
:END:
This way, each org-reveal presentation can have its own settings. An example heading with corresponding settings would look like:
* My org-reveal presentation among many within the same Org-mode file
:PROPERTIES:
:reveal_overview: t
:EXPORT_AUTHOR: Test Author
:EXPORT_DATE: 2018-01-01
:EXPORT_TITLE: My Title
:EXPORT_EMAIL: [email protected]
:EXPORT_OPTIONS: num:nil toc:nil reveal_keyboard:t reveal_overview:t
:EXPORT_REVEAL_HLEVEL: 3
:EXPORT_REVEAL_MARGIN: 200
:END:
:reveal_background_position: absolute
:reveal_extra_attr: height: 200px; bottom: -700px; border-radius: 10px; padding: 20px
Courtesy to:
The powerful Org-mode,
the impressive Reveal.js
and the precise MathJax