Created by yjwen.
#+REVEAL_PLUGINS: (markdown notes) #+REVEAL_EXTRA_CSS: ./local.css * Reveal.js and Org-Reveal - *Reveal.js* is a tool for creating good-looking HTML presentations, authored by [[http://hakim.se/][Hakim El Hattab]]. \\ For an example of a reveal.js presentation, see [[http://lab.hakim.se/reveal-js/#/][here]]. - *Org-Reveal* exports your [[http://orgmode.org/][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. - Latest org-mode. - ox-reveal.el. - htmlize.el (optional, for syntax highlighting). - And, of course, emacs. ** Obtain Reveal.js Download Reveal.js packages from [[https://github.com/hakimel/reveal.js/][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/ ** Obtain org-mode *Note*: Org-reveal relies on the Org-mode 8.0 export frame work. Pre-packaged org-mode may be out-of-date. If in doubt, use the latest development version from the repository. #+BEGIN_SRC sh $ git clone git://orgmode.org/org-mode.git #+END_SRC Follow the [[http://orgmode.org/worg/dev/org-build-system.html][online instruction]] to build and install Org-mode. ** Obtain Org-reveal Download the latest Org-reveal package from [[https://github.com/yjwen/org-reveal][the Org-reveal GitHub page]]. Or clone the GitHub repository: #+BEGIN_SRC sh $ git clone https://github.com/yjwen/org-reveal.git #+END_SRC Copy =ox-reveal.el= to the Org-mode installation directory. Add the following statement to your =.emacs= file. #+BEGIN_SRC lisp (require 'ox-reveal) #+END_SRC * 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: #+BEGIN_SRC lisp (setq org-reveal-root "file:///d:/reveal.js") #+END_SRC *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. ** 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]] #+BEGIN_SRC org ,#+REVEAL_ROOT: file:///d:/reveal.js #+END_SRC Set your =REVEAL_ROOT= to the following URL to download reveal.js from a CDN instead of downloading a local copy. #+BEGIN_SRC org ,#+REVEAL_ROOT: http://cdn.jsdelivr.net/reveal.js/3.0.0/ #+END_SRC ** 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: #+BEGIN_SRC org ,* H1 ,* H2 ,** H2.1 ,*** H2.1.1 ,* H3 #+END_SRC 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. [[./images/hlevel.png]] 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. [[./images/hlevel2.png]] *** 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. #+BEGIN_SRC lisp (setq org-reveal-hlevel 2) #+END_SRC * Setting Org files local HLevel to option =REVEAL_HLEVEL=. #+BEGIN_SRC org ,#+REVEAL_HLEVEL 2 #+END_SRC ** 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 #+BEGIN_SRC org ,#+REVEAL: split #+END_SRC #+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 Slide Background Slide background can be set to a color, an image or a repeating image array by setting heading properties. *** Single Colored Background :PROPERTIES: :reveal_background: #543210 :END: Set property =reveal_background= to either an RGB color value, or any supported CSS color format. #+BEGIN_SRC org ,*** Single Colored Background :PROPERTIES: :reveal_background: #123456 :END: #+END_SRC *** Single Image Background :PROPERTIES: :reveal_background: ./images/whale.jpg :reveal_background_trans: slide :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. #+BEGIN_SRC org ,*** Single Image Background :PROPERTIES: :reveal_background: ./images/whale.jpg :reveal_background_trans: slide :END: #+END_SRC *** Repeating Image Background :PROPERTIES: :reveal_background: ./images/whale.jpg :reveal_background_size: 200px :reveal_background_repeat: repeat :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. #+BEGIN_SRC org ,*** Repeating Image Background :PROPERTIES: :reveal_background: ./images/whale.jpg :reveal_background_size: 200px :reveal_background_repeat: repeat :END: #+END_SRC *** 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 [[https://github.com/hakimel/reveal.js/#slide-number][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]]). ** Fragmented Contents Make contents fragmented (show up one-by-one) by setting option =ATTR_REVEAL= with property ":frag frag-style", as illustrated below. #+ATTR_REVEAL: :frag roll-in Paragraphs can be fragmented. #+ATTR_REVEAL: :frag roll-in - Lists can - be fragmented. #+ATTR_REVEAL: :frag roll-in Pictures, tables and many other HTML elements can be fragmented. *** Fragment Styles Available fragment styles are: #+ATTR_REVEAL: :frag t * 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. #+ATTR_REVEAL: :frag t :frag_idx 3 And, this paragraph shows at last. #+ATTR_REVEAL: :frag t :frag_idx 2 This paragraph shows secondly. #+ATTR_REVEAL: :frag t :frag_idx 1 This paragraph shows at first. *** List Fragments ~#+ATTR_REVEAL: :frag frag-style~ above a list defines fragment style for the list as a whole. #+ATTR_REVEAL: :frag grow 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. #+REVEAL: split An example: #+BEGIN_SRC org ,#+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. #+END_SRC #+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. #+REVEAL: split 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. #+BEGIN_SRC org ,#+ATTR_REVEAL: :frag (appear) * I appear. * I appear. * I appear. #+END_SRC #+ATTR_REVEAL: :frag (appear) * I appear. * I appear. * I appear. ** Data State :PROPERTIES: :reveal_data_state: alert :END: Set property =reveal_data_state= to headings to change this slide's display style, as illustrated above. Available data states are: alert|blackout|soothe. ** 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_overview= - Custom variables:\\ =org-reveal-control=, =org-reveal-progress=, =org-reveal-history=, =org-reveal-center=, =org-reveal-rolling-links=, =org-reveal-keyboard=, =org-reveal-overview= For an example, please refer to the heading part of this document. ** 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 [[http://www.haskell.org/haskellwiki/The_Fibonacci_sequence][Haskell Wiki]]. #+BEGIN_SRC haskell fibs = 0 : 1 : next fibs where next (a : t@(b:_)) = (a+b) : next t #+END_SRC If you saw odd indentation, please set variable =org-html-indent= to =nil= and export again. *** Using highlight.js You can also use [[http://hightlightjs.org][highlight.js]], by adding ~highlight~ to the Reveal.js plugin list. #+BEGIN_SRC org ,#+REVEAL_PLUGINS: (highlight) #+END_SRC 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. ** MathJax :PROPERTIES: :CUSTOM_ID: my-heading :END: ${n! \over k!(n-k)!} = {n \choose k}$ LateX equation are rendered in native HTML5 contents. *IMPORTANT*: Displaying equations requires internet connection to [[http://mathjax.org/][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 == 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: #+REVEAL_HTML: ** 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. #+BEGIN_SRC org ,* Heading 1 Some contents. ,#+BEGIN_NOTES Enter speaker notes here. ,#+END_NOTES #+END_SRC #+REVEAL: split 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. #+REVEAL: split 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: #+BEGIN_SRC org #+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) #+END_SRC 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. #+BEGIN_SRC org ,#+REVEAL_EXTRA_CSS: url-to-custom-stylesheet.css #+END_SRC ** 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. #+BEGIN_SRC org ,#+REVEAL_PLUGINS: (markdown highlight) #+END_SRC ** Extra Dependent Script Set =REVEAL_EXTRA_JS= to the url of extra reveal.js dependent script if necessary. #+BEGIN_SRC org ,#+REVEAL_EXTRA_JS: url-to-custom-script.js #+END_SRC ** 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 necessary Reveal.js scripts will be embedded into the exported HTML file, to make an portable HTML. Attention: This needs locally available reveal.js files! #+BEGIN_SRC org ,#+OPTIONS: reveal_single_file:t #+END_SRC 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.* ** 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= #+BEGIN_SRC org ,#+OPTIONS: num:nil #+END_SRC ** 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]]. * [[#my-heading][Heading]] with a =CUSTOM_ID= property. ** 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~. * Thanks Courtesy to: #+ATTR_REVEAL: :frag roll-in The powerful Org-mode, #+ATTR_REVEAL: :frag roll-in the impressive Reveal.js #+ATTR_REVEAL: :frag roll-in and the precise MathJax