开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

Introduction to Org-Reveal

Table of Contents

Title links are for viewing within org-mode buffer only. Github viewers please use the =(gh)= links.

• Table of Contents(gh)
• Reveal.js and Org-Reveal(gh)
• Requirements and Installation(gh)
  • Install Reveal.js(gh)
  • Install org-reveal from MELPA(gh)
  • Install org-reveal from GitHub(gh)

• Configuration(gh)
  • Set the location of Reveal.js(gh)
    • Url form for file location(gh)
  • First Try(gh)
  • The HLevel(gh)
    • HLevel’s Effects on Slides Layout(gh)
    • Configure HLevel’s Value(gh)
  • Force Split(gh)

• Select Theme(gh)
• Set The Title Slide(gh)
  • Customize the Title Slide(gh)
  • Title Slide State(gh)
• Set Slide Background(gh)
  • Single Colored Background(gh)
  • Single Image Background(gh)
  • Repeating Image Background(gh)
  • Title Slide Background Image(gh)
  • Table of Contents Slide Background Image(gh)
  • Background for all slides(gh)

• Slide Size(gh)
• Slide Numbering(gh)
• Slide Header/Footer(gh)
• Fragmented Contents(gh)
  • Fragment Styles(gh)
  • Fragment Index(gh)
  • List Fragments(gh)

• Initialization options(gh)
• Third-Party Plugins(gh)
• Highlight Source Code(gh)
  • Using highlight.js(gh)
• Auto-Animate (gh)
• Editable Source Code(gh)
• MathJax(gh)

• Preamble and Postamble(gh)
  • Generating Pre/Postamble by Emacs-Lisp Functions(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)

• Tips(gh)
  • Managing Table of Contents(gh)
  • Internal Links(gh)
  • Custom JS(gh)
  • Executable Source Blocks(gh)
    • HTML Src Block(gh)
    • Javascript Src Block(gh)
    • Perl Src Block (not klipsified)(gh)
  • Properties for Sub-headings(gh)
  • Customize iframe background slide(gh)
• Thanks(gh)

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 https://code.orgmode.org/bzg/org-mode

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: https://cdn.jsdelivr.net/npm/reveal.js

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.

To repeat the heading title on the split slide, please insert #+REVEAL: split:t instead.

Select Theme

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.

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

There are 3 ways to customize the title slide.

1. Set variable org-reveal-title-slide to a string of HTML markups.
2. Set reveal_title_slide in the #+OPTIONS: line to a string of HTML markups.
3. 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:

Title Slide State

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.

Set Slide Background

Slide background can be set to a color, an image, a repeating image array or an iframe 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, 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:

Iframe background

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:

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.
• REVEAL_TITLE_SLIDE_BACKGROUND_OPACITY: Set the background opacity.

Table of Contents Slide Background Image

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 to repeat to repeat the image.
• REVEAL_TOC_SLIDE_BACKGROUND_OPACITY: Set the background opacity.

Background for all slides

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.

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 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.

Slide Numbering

To enable slide numbers, please add the following Reveal.js initial option.

#+REVEAL_INIT_OPTIONS: slideNumber:true

Other possible choice for slide numbers are:

Slide Header/Footer

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.

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.

Initialization options

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.

Third-Party Plugins

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.

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 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.

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.

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

Auto-Animate

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

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 javascript, 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