README.md

   1 # reveal.js [![Build Status](https://travis-ci.org/hakimel/reveal.js.svg?branch=master)](https://travis-ci.org/hakimel/reveal.js) <a href="https://slides.com?ref=github"><img src="https://s3.amazonaws.com/static.slid.es/images/slides-github-banner-320x40.png?1" alt="Slides" width="160" height="20"></a>
   2
   3 A framework for easily creating beautiful presentations using HTML. [Check out the live demo](http://lab.hakim.se/reveal-js/).
   4
   5 reveal.js comes with a broad range of features including [nested slides](https://github.com/hakimel/reveal.js#markup), [Markdown contents](https://github.com/hakimel/reveal.js#markdown), [PDF export](https://github.com/hakimel/reveal.js#pdf-export), [speaker notes](https://github.com/hakimel/reveal.js#speaker-notes) and a [JavaScript API](https://github.com/hakimel/reveal.js#api). There's also a fully featured visual editor and platform for sharing reveal.js presentations at [slides.com](https://slides.com?ref=github).
   6
   7 ## Table of contents
   8 - [Online Editor](#online-editor)
   9 - [Instructions](#instructions)
  10   - [Markup](#markup)
  11   - [Markdown](#markdown)
  12   - [Element Attributes](#element-attributes)
  13   - [Slide Attributes](#slide-attributes)
  14 - [Configuration](#configuration)
  15 - [Presentation Size](#presentation-size)
  16 - [Dependencies](#dependencies)
  17 - [Ready Event](#ready-event)
  18 - [Auto-sliding](#auto-sliding)
  19 - [Keyboard Bindings](#keyboard-bindings)
  20 - [Touch Navigation](#touch-navigation)
  21 - [Lazy Loading](#lazy-loading)
  22 - [API](#api)
  23   - [Slide Changed Event](#slide-changed-event)
  24   - [Presentation State](#presentation-state)
  25   - [Slide States](#slide-states)
  26   - [Slide Backgrounds](#slide-backgrounds)
  27   - [Parallax Background](#parallax-background)
  28   - [Slide Transitions](#slide-transitions)
  29   - [Internal links](#internal-links)
  30   - [Fragments](#fragments)
  31   - [Fragment events](#fragment-events)
  32   - [Code syntax highlighting](#code-syntax-highlighting)
  33   - [Slide number](#slide-number)
  34   - [Overview mode](#overview-mode)
  35   - [Fullscreen mode](#fullscreen-mode)
  36   - [Embedded media](#embedded-media)
  37   - [Stretching elements](#stretching-elements)
  38   - [postMessage API](#postmessage-api)
  39 - [PDF Export](#pdf-export)
  40 - [Theming](#theming)
  41 - [Speaker Notes](#speaker-notes)
  42   - [Share and Print Speaker Notes](#share-and-print-speaker-notes)
  43   - [Server Side Speaker Notes](#server-side-speaker-notes)
  44 - [Multiplexing](#multiplexing)
  45   - [Master presentation](#master-presentation)
  46   - [Client presentation](#client-presentation)
  47   - [Socket.io server](#socketio-server)
  48 - [MathJax](#mathjax)
  49 - [Installation](#installation)
  50   - [Basic setup](#basic-setup)
  51   - [Full setup](#full-setup)
  52   - [Folder Structure](#folder-structure)
  53 - [License](#license)
  54
  55 #### More reading
  56 - [Changelog](https://github.com/hakimel/reveal.js/releases): Up-to-date version history.
  57 - [Examples](https://github.com/hakimel/reveal.js/wiki/Example-Presentations): Presentations created with reveal.js, add your own!
  58 - [Browser Support](https://github.com/hakimel/reveal.js/wiki/Browser-Support): Explanation of browser support and fallbacks.
  59 - [Plugins](https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware): A list of plugins that can be used to extend reveal.js.
  60
  61 ## Online Editor
  62
  63 Presentations are written using HTML or Markdown but there's also an online editor for those of you who prefer a graphical interface. Give it a try at [https://slides.com](https://slides.com?ref=github).
  64
  65
  66 ## Instructions
  67
  68 ### Markup
  69
  70 Here's a barebones example of a fully working reveal.js presentation:
  71 ```html
  72 <html>
  73         <head>
  74                 <link rel="stylesheet" href="css/reveal.css">
  75                 <link rel="stylesheet" href="css/theme/white.css">
  76         </head>
  77         <body>
  78                 <div class="reveal">
  79                         <div class="slides">
  80                                 <section>Slide 1</section>
  81                                 <section>Slide 2</section>
  82                         </div>
  83                 </div>
  84                 <script src="js/reveal.js"></script>
  85                 <script>
  86                         Reveal.initialize();
  87                 </script>
  88         </body>
  89 </html>
  90 ```
  91
  92 The presentation markup hierarchy needs to be `.reveal > .slides > section` where the `section` represents one slide and can be repeated indefinitely. If you place multiple `section` elements inside of another `section` they will be shown as vertical slides. The first of the vertical slides is the "root" of the others (at the top), and will be included in the horizontal sequence. For example:
  93
  94 ```html
  95 <div class="reveal">
  96         <div class="slides">
  97                 <section>Single Horizontal Slide</section>
  98                 <section>
  99                         <section>Vertical Slide 1</section>
 100                         <section>Vertical Slide 2</section>
 101                 </section>
 102         </div>
 103 </div>
 104 ```
 105
 106 ### Markdown
 107
 108 It's possible to write your slides using Markdown. To enable Markdown, add the ```data-markdown``` attribute to your ```<section>``` elements and wrap the contents in a ```<script type="text/template">``` like the example below.
 109
 110 This is based on [data-markdown](https://gist.github.com/1343518) from [Paul Irish](https://github.com/paulirish) modified to use [marked](https://github.com/chjj/marked) to support [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown). Sensitive to indentation (avoid mixing tabs and spaces) and line breaks (avoid consecutive breaks).
 111
 112 ```html
 113 <section data-markdown>
 114         <script type="text/template">
 115                 ## Page title
 116
 117                 A paragraph with some text and a [link](http://hakim.se).
 118         </script>
 119 </section>
 120 ```
 121
 122 #### External Markdown
 123
 124 You can write your content as a separate file and have reveal.js load it at runtime. Note the separator arguments which determine how slides are delimited in the external file. The ```data-charset``` attribute is optional and specifies which charset to use when loading the external file.
 125
 126 When used locally, this feature requires that reveal.js [runs from a local web server](#full-setup).
 127
 128 ```html
 129 <section data-markdown="example.md"
 130          data-separator="^\n\n\n"
 131          data-separator-vertical="^\n\n"
 132          data-separator-notes="^Note:"
 133          data-charset="iso-8859-15">
 134 </section>
 135 ```
 136
 137 #### Element Attributes
 138
 139 Special syntax (in html comment) is available for adding attributes to Markdown elements. This is useful for fragments, amongst other things.
 140
 141 ```html
 142 <section data-markdown>
 143         <script type="text/template">
 144                 - Item 1 <!-- .element: class="fragment" data-fragment-index="2" -->
 145                 - Item 2 <!-- .element: class="fragment" data-fragment-index="1" -->
 146         </script>
 147 </section>
 148 ```
 149
 150 #### Slide Attributes
 151
 152 Special syntax (in html comment) is available for adding attributes to the slide `<section>` elements generated by your Markdown.
 153
 154 ```html
 155 <section data-markdown>
 156         <script type="text/template">
 157         <!-- .slide: data-background="#ff0000" -->
 158                 Markdown content
 159         </script>
 160 </section>
 161 ```
 162
 163
 164 ### Configuration
 165
 166 At the end of your page you need to initialize reveal by running the following code. Note that all config values are optional and will default as specified below.
 167
 168 ```javascript
 169 Reveal.initialize({
 170
 171         // Display controls in the bottom right corner
 172         controls: true,
 173
 174         // Display a presentation progress bar
 175         progress: true,
 176
 177         // Display the page number of the current slide
 178         slideNumber: false,
 179
 180         // Push each slide change to the browser history
 181         history: false,
 182
 183         // Enable keyboard shortcuts for navigation
 184         keyboard: true,
 185
 186         // Enable the slide overview mode
 187         overview: true,
 188
 189         // Vertical centering of slides
 190         center: true,
 191
 192         // Enables touch navigation on devices with touch input
 193         touch: true,
 194
 195         // Loop the presentation
 196         loop: false,
 197
 198         // Change the presentation direction to be RTL
 199         rtl: false,
 200
 201         // Randomizes the order of slides each time the presentation loads
 202         shuffle: false,
 203
 204         // Turns fragments on and off globally
 205         fragments: true,
 206
 207         // Flags if the presentation is running in an embedded mode,
 208         // i.e. contained within a limited portion of the screen
 209         embedded: false,
 210
 211         // Flags if we should show a help overlay when the questionmark
 212         // key is pressed
 213         help: true,
 214
 215         // Flags if speaker notes should be visible to all viewers
 216         showNotes: false,
 217
 218         // Number of milliseconds between automatically proceeding to the
 219         // next slide, disabled when set to 0, this value can be overwritten
 220         // by using a data-autoslide attribute on your slides
 221         autoSlide: 0,
 222
 223         // Stop auto-sliding after user input
 224         autoSlideStoppable: true,
 225
 226         // Use this method for navigation when auto-sliding
 227         autoSlideMethod: Reveal.navigateNext,
 228
 229         // Enable slide navigation via mouse wheel
 230         mouseWheel: false,
 231
 232         // Hides the address bar on mobile devices
 233         hideAddressBar: true,
 234
 235         // Opens links in an iframe preview overlay
 236         previewLinks: false,
 237
 238         // Transition style
 239         transition: 'default', // none/fade/slide/convex/concave/zoom
 240
 241         // Transition speed
 242         transitionSpeed: 'default', // default/fast/slow
 243
 244         // Transition style for full page slide backgrounds
 245         backgroundTransition: 'default', // none/fade/slide/convex/concave/zoom
 246
 247         // Number of slides away from the current that are visible
 248         viewDistance: 3,
 249
 250         // Parallax background image
 251         parallaxBackgroundImage: '', // e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"
 252
 253         // Parallax background size
 254         parallaxBackgroundSize: '', // CSS syntax, e.g. "2100px 900px"
 255
 256         // Number of pixels to move the parallax background per slide
 257         // - Calculated automatically unless specified
 258         // - Set to 0 to disable movement along an axis
 259         parallaxBackgroundHorizontal: null,
 260         parallaxBackgroundVertical: null
 261
 262 });
 263 ```
 264
 265
 266 The configuration can be updated after initialization using the ```configure``` method:
 267
 268 ```javascript
 269 // Turn autoSlide off
 270 Reveal.configure({ autoSlide: 0 });
 271
 272 // Start auto-sliding every 5s
 273 Reveal.configure({ autoSlide: 5000 });
 274 ```
 275
 276
 277 ### Presentation Size
 278
 279 All presentations have a normal size, that is the resolution at which they are authored. The framework will automatically scale presentations uniformly based on this size to ensure that everything fits on any given display or viewport.
 280
 281 See below for a list of configuration options related to sizing, including default values:
 282
 283 ```javascript
 284 Reveal.initialize({
 285
 286         ...
 287
 288         // The "normal" size of the presentation, aspect ratio will be preserved
 289         // when the presentation is scaled to fit different resolutions. Can be
 290         // specified using percentage units.
 291         width: 960,
 292         height: 700,
 293
 294         // Factor of the display size that should remain empty around the content
 295         margin: 0.1,
 296
 297         // Bounds for smallest/largest possible scale to apply to content
 298         minScale: 0.2,
 299         maxScale: 1.5
 300
 301 });
 302 ```
 303
 304 If you wish to disable this behavior and do your own scaling (e.g. using media queries), try these settings:
 305
 306 ```javascript
 307 Reveal.initialize({
 308
 309         ...
 310
 311         width: "100%",
 312         height: "100%",
 313         margin: 0,
 314         minScale: 1,
 315         maxScale: 1
 316 });
 317 ```
 318
 319 ### Dependencies
 320
 321 Reveal.js doesn't _rely_ on any third party scripts to work but a few optional libraries are included by default. These libraries are loaded as dependencies in the order they appear, for example:
 322
 323 ```javascript
 324 Reveal.initialize({
 325         dependencies: [
 326                 // Cross-browser shim that fully implements classList - https://github.com/eligrey/classList.js/
 327                 { src: 'lib/js/classList.js', condition: function() { return !document.body.classList; } },
 328
 329                 // Interpret Markdown in <section> elements
 330                 { src: 'plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
 331                 { src: 'plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
 332
 333                 // Syntax highlight for <code> elements
 334                 { src: 'plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },
 335
 336                 // Zoom in and out with Alt+click
 337                 { src: 'plugin/zoom-js/zoom.js', async: true },
 338
 339                 // Speaker notes
 340                 { src: 'plugin/notes/notes.js', async: true },
 341
 342                 // MathJax
 343                 { src: 'plugin/math/math.js', async: true }
 344         ]
 345 });
 346 ```
 347
 348 You can add your own extensions using the same syntax. The following properties are available for each dependency object:
 349 - **src**: Path to the script to load
 350 - **async**: [optional] Flags if the script should load after reveal.js has started, defaults to false
 351 - **callback**: [optional] Function to execute when the script has loaded
 352 - **condition**: [optional] Function which must return true for the script to be loaded
 353
 354
 355 ### Ready Event
 356
 357 A 'ready' event is fired when reveal.js has loaded all non-async dependencies and is ready to start navigating. To check if reveal.js is already 'ready' you can call `Reveal.isReady()`.
 358
 359 ```javascript
 360 Reveal.addEventListener( 'ready', function( event ) {
 361         // event.currentSlide, event.indexh, event.indexv
 362 } );
 363 ```
 364
 365
 366 ### Auto-sliding
 367
 368 Presentations can be configured to progress through slides automatically, without any user input. To enable this you will need to tell the framework how many milliseconds it should wait between slides:
 369
 370 ```javascript
 371 // Slide every five seconds
 372 Reveal.configure({
 373   autoSlide: 5000
 374 });
 375 ```
 376 When this is turned on a control element will appear that enables users to pause and resume auto-sliding. Alternatively, sliding can be paused or resumed by pressing »a« on the keyboard. Sliding is paused automatically as soon as the user starts navigating. You can disable these controls by specifying ```autoSlideStoppable: false``` in your reveal.js config.
 377
 378 You can also override the slide duration for individual slides and fragments by using the ```data-autoslide``` attribute:
 379
 380 ```html
 381 <section data-autoslide="2000">
 382         <p>After 2 seconds the first fragment will be shown.</p>
 383         <p class="fragment" data-autoslide="10000">After 10 seconds the next fragment will be shown.</p>
 384         <p class="fragment">Now, the fragment is displayed for 2 seconds before the next slide is shown.</p>
 385 </section>
 386 ```
 387
 388 To override the method used for navigation when auto-sliding, you can specify the ```autoSlideMethod``` setting. To only navigate along the top layer and ignore vertical slides, set this to ```Reveal.navigateRight```.
 389
 390 Whenever the auto-slide mode is resumed or paused the ```autoslideresumed``` and ```autoslidepaused``` events are fired.
 391
 392
 393 ### Keyboard Bindings
 394
 395 If you're unhappy with any of the default keyboard bindings you can override them using the ```keyboard``` config option:
 396
 397 ```javascript
 398 Reveal.configure({
 399   keyboard: {
 400     13: 'next', // go to the next slide when the ENTER key is pressed
 401     27: function() {}, // do something custom when ESC is pressed
 402     32: null // don't do anything when SPACE is pressed (i.e. disable a reveal.js default binding)
 403   }
 404 });
 405 ```
 406
 407 ### Touch Navigation
 408
 409 You can swipe to navigate through a presentation on any touch-enabled device. Horizontal swipes change between horizontal slides, vertical swipes change between vertical slides. If you wish to disable this you can set the `touch` config option to false when initializing reveal.js.
 410
 411 If there's some part of your content that needs to remain accessible to touch events you'll need to highlight this by adding a `data-prevent-swipe` attribute to the element. One common example where this is useful is elements that need to be scrolled.
 412
 413
 414 ### Lazy Loading
 415
 416 When working on presentation with a lot of media or iframe content it's important to load lazily. Lazy loading means that reveal.js will only load content for the few slides nearest to the current slide. The number of slides that are preloaded is determined by the `viewDistance` configuration option.
 417
 418 To enable lazy loading all you need to do is change your "src" attributes to "data-src" as shown below. This is supported for image, video, audio and iframe elements. Lazy loaded iframes will also unload when the containing slide is no longer visible.
 419
 420 ```html
 421 <section>
 422   <img data-src="image.png">
 423   <iframe data-src="http://hakim.se"></iframe>
 424   <video>
 425     <source data-src="video.webm" type="video/webm" />
 426     <source data-src="video.mp4" type="video/mp4" />
 427   </video>
 428 </section>
 429 ```
 430
 431
 432 ### API
 433
 434 The ``Reveal`` object exposes a JavaScript API for controlling navigation and reading state:
 435
 436 ```javascript
 437 // Navigation
 438 Reveal.slide( indexh, indexv, indexf );
 439 Reveal.left();
 440 Reveal.right();
 441 Reveal.up();
 442 Reveal.down();
 443 Reveal.prev();
 444 Reveal.next();
 445 Reveal.prevFragment();
 446 Reveal.nextFragment();
 447
 448 // Randomize the order of slides
 449 Reveal.shuffle();
 450
 451 // Toggle presentation states, optionally pass true/false to force on/off
 452 Reveal.toggleOverview();
 453 Reveal.togglePause();
 454 Reveal.toggleAutoSlide();
 455
 456 // Change a config value at runtime
 457 Reveal.configure({ controls: true });
 458
 459 // Returns the present configuration options
 460 Reveal.getConfig();
 461
 462 // Fetch the current scale of the presentation
 463 Reveal.getScale();
 464
 465 // Retrieves the previous and current slide elements
 466 Reveal.getPreviousSlide();
 467 Reveal.getCurrentSlide();
 468
 469 Reveal.getIndices(); // { h: 0, v: 0 } }
 470 Reveal.getProgress(); // 0-1
 471 Reveal.getTotalSlides();
 472
 473 // Returns the speaker notes for the current slide
 474 Reveal.getSlideNotes();
 475
 476 // State checks
 477 Reveal.isFirstSlide();
 478 Reveal.isLastSlide();
 479 Reveal.isOverview();
 480 Reveal.isPaused();
 481 Reveal.isAutoSliding();
 482 ```
 483
 484 ### Slide Changed Event
 485
 486 A 'slidechanged' event is fired each time the slide is changed (regardless of state). The event object holds the index values of the current slide as well as a reference to the previous and current slide HTML nodes.
 487
 488 Some libraries, like MathJax (see [#226](https://github.com/hakimel/reveal.js/issues/226#issuecomment-10261609)), get confused by the transforms and display states of slides. Often times, this can be fixed by calling their update or render function from this callback.
 489
 490 ```javascript
 491 Reveal.addEventListener( 'slidechanged', function( event ) {
 492         // event.previousSlide, event.currentSlide, event.indexh, event.indexv
 493 } );
 494 ```
 495
 496 ### Presentation State
 497
 498 The presentation's current state can be fetched by using the `getState` method. A state object contains all of the information required to put the presentation back as it was when `getState` was first called. Sort of like a snapshot. It's a simple object that can easily be stringified and persisted or sent over the wire.
 499
 500 ```javascript
 501 Reveal.slide( 1 );
 502 // we're on slide 1
 503
 504 var state = Reveal.getState();
 505
 506 Reveal.slide( 3 );
 507 // we're on slide 3
 508
 509 Reveal.setState( state );
 510 // we're back on slide 1
 511 ```
 512
 513 ### Slide States
 514
 515 If you set ``data-state="somestate"`` on a slide ``<section>``, "somestate" will be applied as a class on the document element when that slide is opened. This allows you to apply broad style changes to the page based on the active slide.
 516
 517 Furthermore you can also listen to these changes in state via JavaScript:
 518
 519 ```javascript
 520 Reveal.addEventListener( 'somestate', function() {
 521         // TODO: Sprinkle magic
 522 }, false );
 523 ```
 524
 525 ### Slide Backgrounds
 526
 527 Slides are contained within a limited portion of the screen by default to allow them to fit any display and scale uniformly. You can apply full page backgrounds outside of the slide area by adding a ```data-background``` attribute to your ```<section>``` elements. Four different types of backgrounds are supported: color, image, video and iframe.
 528
 529 ##### Color Backgrounds
 530 All CSS color formats are supported, like rgba() or hsl().
 531 ```html
 532 <section data-background-color="#ff0000">
 533         <h2>Color</h2>
 534 </section>
 535 ```
 536
 537 ##### Image Backgrounds
 538 By default, background images are resized to cover the full page. Available options:
 539
 540 | Attribute                    | Default    | Description |
 541 | :--------------------------- | :--------- | :---------- |
 542 | data-background-image        |            | URL of the image to show. GIFs restart when the slide opens. |
 543 | data-background-size         | cover      | See [background-size](https://developer.mozilla.org/docs/Web/CSS/background-size) on MDN.  |
 544 | data-background-position     | center     | See [background-position](https://developer.mozilla.org/docs/Web/CSS/background-position) on MDN. |
 545 | data-background-repeat       | no-repeat  | See [background-repeat](https://developer.mozilla.org/docs/Web/CSS/background-repeat) on MDN. |
 546 ```html
 547 <section data-background-image="http://example.com/image.png">
 548         <h2>Image</h2>
 549 </section>
 550 <section data-background-image="http://example.com/image.png" data-background-size="100px" data-background-repeat="repeat">
 551         <h2>This background image will be sized to 100px and repeated</h2>
 552 </section>
 553 ```
 554
 555 ##### Video Backgrounds
 556 Automatically plays a full size video behind the slide.
 557
 558 | Attribute                    | Default | Description |
 559 | :--------------------------- | :------ | :---------- |
 560 | data-background-video        |         | A single video source, or a comma separated list of video sources. |
 561 | data-background-video-loop   | false   | Flags if the video should play repeatedly. |
 562 | data-background-video-muted  | false   | Flags if the audio should be muted. |
 563
 564 ```html
 565 <section data-background-video="https://s3.amazonaws.com/static.slid.es/site/homepage/v1/homepage-video-editor.mp4,https://s3.amazonaws.com/static.slid.es/site/homepage/v1/homepage-video-editor.webm" data-background-video-loop data-background-video-muted>
 566         <h2>Video</h2>
 567 </section>
 568 ```
 569
 570 ##### Iframe Backgrounds
 571 Embeds a web page as a background. Note that since the iframe is in the background layer, behind your slides, it is not possible to interact with the embedded page.
 572 ```html
 573 <section data-background-iframe="https://slides.com">
 574         <h2>Iframe</h2>
 575 </section>
 576 ```
 577
 578 ##### Background Transitions
 579 Backgrounds transition using a fade animation by default. This can be changed to a linear sliding transition by passing ```backgroundTransition: 'slide'``` to the ```Reveal.initialize()``` call. Alternatively you can set ```data-background-transition``` on any section with a background to override that specific transition.
 580
 581
 582 ### Parallax Background
 583
 584 If you want to use a parallax scrolling background, set the first two config properties below when initializing reveal.js (the other two are optional).
 585
 586 ```javascript
 587 Reveal.initialize({
 588
 589         // Parallax background image
 590         parallaxBackgroundImage: '', // e.g. "https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg"
 591
 592         // Parallax background size
 593         parallaxBackgroundSize: '', // CSS syntax, e.g. "2100px 900px" - currently only pixels are supported (don't use % or auto)
 594
 595         // Number of pixels to move the parallax background per slide
 596         // - Calculated automatically unless specified
 597         // - Set to 0 to disable movement along an axis
 598         parallaxBackgroundHorizontal: 200,
 599         parallaxBackgroundVertical: 50
 600
 601 });
 602 ```
 603
 604 Make sure that the background size is much bigger than screen size to allow for some scrolling. [View example](http://lab.hakim.se/reveal-js/?parallaxBackgroundImage=https%3A%2F%2Fs3.amazonaws.com%2Fhakim-static%2Freveal-js%2Freveal-parallax-1.jpg&parallaxBackgroundSize=2100px%20900px).
 605
 606
 607
 608 ### Slide Transitions
 609 The global presentation transition is set using the ```transition``` config value. You can override the global transition for a specific slide by using the ```data-transition``` attribute:
 610
 611 ```html
 612 <section data-transition="zoom">
 613         <h2>This slide will override the presentation transition and zoom!</h2>
 614 </section>
 615
 616 <section data-transition-speed="fast">
 617         <h2>Choose from three transition speeds: default, fast or slow!</h2>
 618 </section>
 619 ```
 620
 621 You can also use different in and out transitions for the same slide:
 622
 623 ```html
 624 <section data-transition="slide">
 625     The train goes on …
 626 </section>
 627 <section data-transition="slide">
 628     and on …
 629 </section>
 630 <section data-transition="slide-in fade-out">
 631     and stops.
 632 </section>
 633 <section data-transition="fade-in slide-out">
 634     (Passengers entering and leaving)
 635 </section>
 636 <section data-transition="slide">
 637     And it starts again.
 638 </section>
 639 ```
 640
 641
 642 ### Internal links
 643
 644 It's easy to link between slides. The first example below targets the index of another slide whereas the second targets a slide with an ID attribute (```<section id="some-slide">```):
 645
 646 ```html
 647 <a href="#/2/2">Link</a>
 648 <a href="#/some-slide">Link</a>
 649 ```
 650
 651 You can also add relative navigation links, similar to the built in reveal.js controls, by appending one of the following classes on any element. Note that each element is automatically given an ```enabled``` class when it's a valid navigation route based on the current slide.
 652
 653 ```html
 654 <a href="#" class="navigate-left">
 655 <a href="#" class="navigate-right">
 656 <a href="#" class="navigate-up">
 657 <a href="#" class="navigate-down">
 658 <a href="#" class="navigate-prev"> <!-- Previous vertical or horizontal slide -->
 659 <a href="#" class="navigate-next"> <!-- Next vertical or horizontal slide -->
 660 ```
 661
 662
 663 ### Fragments
 664 Fragments are used to highlight individual elements on a slide. Every element with the class ```fragment``` will be stepped through before moving on to the next slide. Here's an example: http://lab.hakim.se/reveal-js/#/fragments
 665
 666 The default fragment style is to start out invisible and fade in. This style can be changed by appending a different class to the fragment:
 667
 668 ```html
 669 <section>
 670         <p class="fragment grow">grow</p>
 671         <p class="fragment shrink">shrink</p>
 672         <p class="fragment fade-out">fade-out</p>
 673         <p class="fragment fade-up">fade-up (also down, left and right!)</p>
 674         <p class="fragment current-visible">visible only once</p>
 675         <p class="fragment highlight-current-blue">blue only once</p>
 676         <p class="fragment highlight-red">highlight-red</p>
 677         <p class="fragment highlight-green">highlight-green</p>
 678         <p class="fragment highlight-blue">highlight-blue</p>
 679 </section>
 680 ```
 681
 682 Multiple fragments can be applied to the same element sequentially by wrapping it, this will fade in the text on the first step and fade it back out on the second.
 683
 684 ```html
 685 <section>
 686         <span class="fragment fade-in">
 687                 <span class="fragment fade-out">I'll fade in, then out</span>
 688         </span>
 689 </section>
 690 ```
 691
 692 The display order of fragments can be controlled using the ```data-fragment-index``` attribute.
 693
 694 ```html
 695 <section>
 696         <p class="fragment" data-fragment-index="3">Appears last</p>
 697         <p class="fragment" data-fragment-index="1">Appears first</p>
 698         <p class="fragment" data-fragment-index="2">Appears second</p>
 699 </section>
 700 ```
 701
 702 ### Fragment events
 703
 704 When a slide fragment is either shown or hidden reveal.js will dispatch an event.
 705
 706 Some libraries, like MathJax (see #505), get confused by the initially hidden fragment elements. Often times this can be fixed by calling their update or render function from this callback.
 707
 708 ```javascript
 709 Reveal.addEventListener( 'fragmentshown', function( event ) {
 710         // event.fragment = the fragment DOM element
 711 } );
 712 Reveal.addEventListener( 'fragmenthidden', function( event ) {
 713         // event.fragment = the fragment DOM element
 714 } );
 715 ```
 716
 717 ### Code syntax highlighting
 718
 719 By default, Reveal is configured with [highlight.js](https://highlightjs.org/) for code syntax highlighting. Below is an example with clojure code that will be syntax highlighted. When the `data-trim` attribute is present, surrounding whitespace is automatically removed.  HTML will be escaped by default. To avoid this, for example if you are using `<mark>` to call out a line of code, add the `data-noescape` attribute to the `<code>` element.
 720
 721 ```html
 722 <section>
 723         <pre><code data-trim data-noescape>
 724 (def lazy-fib
 725   (concat
 726    [0 1]
 727    <mark>((fn rfib [a b]</mark>
 728         (lazy-cons (+ a b) (rfib b (+ a b)))) 0 1)))
 729         </code></pre>
 730 </section>
 731 ```
 732
 733 ### Slide number
 734 If you would like to display the page number of the current slide you can do so using the ```slideNumber``` configuration value.
 735
 736 ```javascript
 737 // Shows the slide number using default formatting
 738 Reveal.configure({ slideNumber: true });
 739
 740 // Slide number formatting can be configured using these variables:
 741 //  "h.v":      horizontal . vertical slide number (default)
 742 //  "h/v":      horizontal / vertical slide number
 743 //    "c":      flattened slide number
 744 //  "c/t":      flattened slide number / total slides
 745 Reveal.configure({ slideNumber: 'c/t' });
 746
 747 ```
 748
 749
 750 ### Overview mode
 751
 752 Press "Esc" or "o" keys to toggle the overview mode on and off. While you're in this mode, you can still navigate between slides,
 753 as if you were at 1,000 feet above your presentation. The overview mode comes with a few API hooks:
 754
 755 ```javascript
 756 Reveal.addEventListener( 'overviewshown', function( event ) { /* ... */ } );
 757 Reveal.addEventListener( 'overviewhidden', function( event ) { /* ... */ } );
 758
 759 // Toggle the overview mode programmatically
 760 Reveal.toggleOverview();
 761 ```
 762
 763 ### Fullscreen mode
 764 Just press »F« on your keyboard to show your presentation in fullscreen mode. Press the »ESC« key to exit fullscreen mode.
 765
 766
 767 ### Embedded media
 768 Embedded HTML5 `<video>`/`<audio>` and YouTube iframes are automatically paused when you navigate away from a slide. This can be disabled by decorating your element with a `data-ignore` attribute.
 769
 770 Add `data-autoplay` to your media element if you want it to automatically start playing when the slide is shown:
 771
 772 ```html
 773 <video data-autoplay src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4"></video>
 774 ```
 775
 776 Additionally the framework automatically pushes two [post messages](https://developer.mozilla.org/en-US/docs/Web/API/Window.postMessage) to all iframes, ```slide:start``` when the slide containing the iframe is made visible and ```slide:stop``` when it is hidden.
 777
 778
 779 ### Stretching elements
 780 Sometimes it's desirable to have an element, like an image or video, stretch to consume as much space as possible within a given slide. This can be done by adding the ```.stretch``` class to an element as seen below:
 781
 782 ```html
 783 <section>
 784         <h2>This video will use up the remaining space on the slide</h2>
 785     <video class="stretch" src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4"></video>
 786 </section>
 787 ```
 788
 789 Limitations:
 790 - Only direct descendants of a slide section can be stretched
 791 - Only one descendant per slide section can be stretched
 792
 793
 794 ### postMessage API
 795 The framework has a built-in postMessage API that can be used when communicating with a presentation inside of another window. Here's an example showing how you'd make a reveal.js instance in the given window proceed to slide 2:
 796
 797 ```javascript
 798 <window>.postMessage( JSON.stringify({ method: 'slide', args: [ 2 ] }), '*' );
 799 ```
 800
 801 When reveal.js runs inside of an iframe it can optionally bubble all of its events to the parent. Bubbled events are stringified JSON with three fields: namespace, eventName and state. Here's how you subscribe to them from the parent window:
 802
 803 ```javascript
 804 window.addEventListener( 'message', function( event ) {
 805         var data = JSON.parse( event.data );
 806         if( data.namespace === 'reveal' && data.eventName ==='slidechanged' ) {
 807                 // Slide changed, see data.state for slide number
 808         }
 809 } );
 810 ```
 811
 812 This cross-window messaging can be toggled on or off using configuration flags.
 813
 814 ```javascript
 815 Reveal.initialize({
 816         ...,
 817
 818         // Exposes the reveal.js API through window.postMessage
 819         postMessage: true,
 820
 821         // Dispatches all reveal.js events to the parent window through postMessage
 822         postMessageEvents: false
 823 });
 824 ```
 825
 826
 827 ## PDF Export
 828
 829 Presentations can be exported to PDF via a special print stylesheet. This feature requires that you use [Google Chrome](http://google.com/chrome) or [Chromium](https://www.chromium.org/Home).
 830 Here's an example of an exported presentation that's been uploaded to SlideShare: http://www.slideshare.net/hakimel/revealjs-300.
 831
 832 1. Open your presentation with `print-pdf` included anywhere in the query string. This triggers the default index HTML to load the PDF print stylesheet ([css/print/pdf.css](https://github.com/hakimel/reveal.js/blob/master/css/print/pdf.css)). You can test this with [lab.hakim.se/reveal-js?print-pdf](http://lab.hakim.se/reveal-js?print-pdf).
 833 2. Open the in-browser print dialog (CTRL/CMD+P).
 834 3. Change the **Destination** setting to **Save as PDF**.
 835 4. Change the **Layout** to **Landscape**.
 836 5. Change the **Margins** to **None**.
 837 6. Enable the **Background graphics** option.
 838 7. Click **Save**.
 839
 840 ![Chrome Print Settings](https://s3.amazonaws.com/hakim-static/reveal-js/pdf-print-settings-2.png)
 841
 842 Alternatively you can use the [decktape](https://github.com/astefanutti/decktape) project.
 843
 844 ## Theming
 845
 846 The framework comes with a few different themes included:
 847
 848 - black: Black background, white text, blue links (default theme)
 849 - white: White background, black text, blue links
 850 - league: Gray background, white text, blue links (default theme for reveal.js < 3.0.0)
 851 - beige: Beige background, dark text, brown links
 852 - sky: Blue background, thin dark text, blue links
 853 - night: Black background, thick white text, orange links
 854 - serif: Cappuccino background, gray text, brown links
 855 - simple: White background, black text, blue links
 856 - solarized: Cream-colored background, dark green text, blue links
 857
 858 Each theme is available as a separate stylesheet. To change theme you will need to replace **black** below with your desired theme name in index.html:
 859
 860 ```html
 861 <link rel="stylesheet" href="css/theme/black.css" id="theme">
 862 ```
 863
 864 If you want to add a theme of your own see the instructions here: [/css/theme/README.md](https://github.com/hakimel/reveal.js/blob/master/css/theme/README.md).
 865
 866
 867 ## Speaker Notes
 868
 869 reveal.js comes with a speaker notes plugin which can be used to present per-slide notes in a separate browser window. The notes window also gives you a preview of the next upcoming slide so it may be helpful even if you haven't written any notes. Press the 's' key on your keyboard to open the notes window.
 870
 871 Notes are defined by appending an ```<aside>``` element to a slide as seen below. You can add the ```data-markdown``` attribute to the aside element if you prefer writing notes using Markdown.
 872
 873 Alternatively you can add your notes in a `data-notes` attribute on the slide. Like `<section data-notes="Something important"></section>`.
 874
 875 When used locally, this feature requires that reveal.js [runs from a local web server](#full-setup).
 876
 877 ```html
 878 <section>
 879         <h2>Some Slide</h2>
 880
 881         <aside class="notes">
 882                 Oh hey, these are some notes. They'll be hidden in your presentation, but you can see them if you open the speaker notes window (hit 's' on your keyboard).
 883         </aside>
 884 </section>
 885 ```
 886
 887 If you're using the external Markdown plugin, you can add notes with the help of a special delimiter:
 888
 889 ```html
 890 <section data-markdown="example.md" data-separator="^\n\n\n" data-separator-vertical="^\n\n" data-separator-notes="^Note:"></section>
 891
 892 # Title
 893 ## Sub-title
 894
 895 Here is some content...
 896
 897 Note:
 898 This will only display in the notes window.
 899 ```
 900
 901 #### Share and Print Speaker Notes
 902
 903 Notes are only visible to the speaker inside of the speaker view. If you wish to share your notes with others you can initialize reveal.js with the `showNotes` config value set to `true`. Notes will appear along the bottom of the presentations.
 904
 905 When `showNotes` is enabled notes are also included when you [export to PDF](https://github.com/hakimel/reveal.js#pdf-export).
 906
 907 ## Server Side Speaker Notes
 908
 909 In some cases it can be desirable to run notes on a separate device from the one you're presenting on. The Node.js-based notes plugin lets you do this using the same note definitions as its client side counterpart. Include the required scripts by adding the following dependencies:
 910
 911 ```javascript
 912 Reveal.initialize({
 913         ...
 914
 915         dependencies: [
 916                 { src: 'socket.io/socket.io.js', async: true },
 917                 { src: 'plugin/notes-server/client.js', async: true }
 918         ]
 919 });
 920 ```
 921
 922 Then:
 923
 924 1. Install [Node.js](http://nodejs.org/) (1.0.0 or later)
 925 2. Run ```npm install```
 926 3. Run ```node plugin/notes-server```
 927
 928
 929 ## Multiplexing
 930
 931 The multiplex plugin 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-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/).
 932
 933 The multiplex plugin needs the following 3 things to operate:
 934
 935 1. Master presentation that has control
 936 2. Client presentations that follow the master
 937 3. Socket.io server to broadcast events from the master to the clients
 938
 939 More details:
 940
 941 #### Master presentation
 942 Served from a static file server accessible (preferably) only to the presenter. This need only be on your (the presenter's) computer. (It's safer to run the master presentation from your own computer, so if the venue's Internet goes down it doesn't stop the show.) An example would be to execute the following commands in the directory of your master presentation:
 943
 944 1. ```npm install node-static```
 945 2. ```static```
 946
 947 If you want to use the speaker notes plugin with your master presentation then make sure you have the speaker notes plugin configured correctly along with the configuration shown below, then execute ```node plugin/notes-server``` in the directory of your master presentation. The configuration below will cause it to connect to the socket.io server as a master, as well as launch your speaker-notes/static-file server.
 948
 949 You can then access your master presentation at ```http://localhost:1947```
 950
 951 Example configuration:
 952 ```javascript
 953 Reveal.initialize({
 954         // other options...
 955
 956         multiplex: {
 957                 // Example values. To generate your own, see the socket.io server instructions.
 958                 secret: '13652805320794272084', // Obtained from the socket.io server. Gives this (the master) control of the presentation
 959                 id: '1ea875674b17ca76', // Obtained from socket.io server
 960                 url: 'https://reveal-js-multiplex-ccjbegmaii.now.sh' // Location of socket.io server
 961         },
 962
 963         // Don't forget to add the dependencies
 964         dependencies: [
 965                 { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true },
 966                 { src: 'plugin/multiplex/master.js', async: true },
 967
 968                 // and if you want speaker notes
 969                 { src: 'plugin/notes-server/client.js', async: true }
 970
 971                 // other dependencies...
 972         ]
 973 });
 974 ```
 975
 976 #### Client presentation
 977 Served from a publicly accessible static file server. Examples include: GitHub Pages, Amazon S3, Dreamhost, Akamai, etc. The more reliable, the better. Your audience can then access the client presentation via ```http://example.com/path/to/presentation/client/index.html```, with the configuration below causing them to connect to the socket.io server as clients.
 978
 979 Example configuration:
 980 ```javascript
 981 Reveal.initialize({
 982         // other options...
 983
 984         multiplex: {
 985                 // Example values. To generate your own, see the socket.io server instructions.
 986                 secret: null, // null so the clients do not have control of the master presentation
 987                 id: '1ea875674b17ca76', // id, obtained from socket.io server
 988                 url: 'https://reveal-js-multiplex-ccjbegmaii.now.sh' // Location of socket.io server
 989         },
 990
 991         // Don't forget to add the dependencies
 992         dependencies: [
 993                 { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true },
 994                 { src: 'plugin/multiplex/client.js', async: true }
 995
 996                 // other dependencies...
 997         ]
 998 });
 999 ```
1000
1001 #### Socket.io server
1002 Server that receives the slideChanged events from the master presentation and broadcasts them out to the connected client presentations. This needs to be publicly accessible. You can run your own socket.io server with the commands:
1003
1004 1. ```npm install```
1005 2. ```node plugin/multiplex```
1006
1007 Or you use the socket.io server at [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/).
1008
1009 You'll need to generate a unique secret and token pair for your master and client presentations. To do so, visit ```http://example.com/token```, where ```http://example.com``` is the location of your socket.io server. Or if you're going to use the socket.io server at [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/), visit [https://reveal-js-multiplex-ccjbegmaii.now.sh/token](https://reveal-js-multiplex-ccjbegmaii.now.sh/token).
1010
1011 You are very welcome to point your presentations at the Socket.io server running at [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/), but availability and stability are not guaranteed. For anything mission critical I recommend you run your own server. It is simple to deploy to nodejitsu, heroku, your own environment, etc.
1012
1013 ##### socket.io server as file static server
1014
1015 The socket.io server can play the role of static file server for your client presentation, as in the example at [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/). (Open [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/) in two browsers. Navigate through the slides on one, and the other will update to match.)
1016
1017 Example configuration:
1018 ```javascript
1019 Reveal.initialize({
1020         // other options...
1021
1022         multiplex: {
1023                 // Example values. To generate your own, see the socket.io server instructions.
1024                 secret: null, // null so the clients do not have control of the master presentation
1025                 id: '1ea875674b17ca76', // id, obtained from socket.io server
1026                 url: 'example.com:80' // Location of your socket.io server
1027         },
1028
1029         // Don't forget to add the dependencies
1030         dependencies: [
1031                 { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true },
1032                 { src: 'plugin/multiplex/client.js', async: true }
1033
1034                 // other dependencies...
1035         ]
1036 ```
1037
1038 It can also play the role of static file server for your master presentation and client presentations at the same time (as long as you don't want to use speaker notes). (Open [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/) in two browsers. Navigate through the slides on one, and the other will update to match. Navigate through the slides on the second, and the first will update to match.) This is probably not desirable, because you don't want your audience to mess with your slides while you're presenting. ;)
1039
1040 Example configuration:
1041 ```javascript
1042 Reveal.initialize({
1043         // other options...
1044
1045         multiplex: {
1046                 // Example values. To generate your own, see the socket.io server instructions.
1047                 secret: '13652805320794272084', // Obtained from the socket.io server. Gives this (the master) control of the presentation
1048                 id: '1ea875674b17ca76', // Obtained from socket.io server
1049                 url: 'example.com:80' // Location of your socket.io server
1050         },
1051
1052         // Don't forget to add the dependencies
1053         dependencies: [
1054                 { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true },
1055                 { src: 'plugin/multiplex/master.js', async: true },
1056                 { src: 'plugin/multiplex/client.js', async: true }
1057
1058                 // other dependencies...
1059         ]
1060 });
1061 ```
1062
1063 ## MathJax
1064
1065 If you want to display math equations in your presentation you can easily do so by including this plugin. The plugin is a very thin wrapper around the [MathJax](http://www.mathjax.org/) library. To use it you'll need to include it as a reveal.js dependency, [find our more about dependencies here](#dependencies).
1066
1067 The plugin defaults to using [LaTeX](http://en.wikipedia.org/wiki/LaTeX) but that can be adjusted through the ```math``` configuration object. Note that MathJax is loaded from a remote server. If you want to use it offline you'll need to download a copy of the library and adjust the ```mathjax``` configuration value.
1068
1069 Below is an example of how the plugin can be configured. If you don't intend to change these values you do not need to include the ```math``` config object at all.
1070
1071 ```js
1072 Reveal.initialize({
1073
1074         // other options ...
1075
1076         math: {
1077                 mathjax: 'https://cdn.mathjax.org/mathjax/latest/MathJax.js',
1078                 config: 'TeX-AMS_HTML-full'  // See http://docs.mathjax.org/en/latest/config-files.html
1079         },
1080
1081         dependencies: [
1082                 { src: 'plugin/math/math.js', async: true }
1083         ]
1084
1085 });
1086 ```
1087
1088 Read MathJax's documentation if you need [HTTPS delivery](http://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn) or serving of [specific versions](http://docs.mathjax.org/en/latest/configuration.html#loading-mathjax-from-the-cdn) for stability.
1089
1090
1091 ## Installation
1092
1093 The **basic setup** is for authoring presentations only. The **full setup** gives you access to all reveal.js features and plugins such as speaker notes as well as the development tasks needed to make changes to the source.
1094
1095 ### Basic setup
1096
1097 The core of reveal.js is very easy to install. You'll simply need to download a copy of this repository and open the index.html file directly in your browser.
1098
1099 1. Download the latest version of reveal.js from <https://github.com/hakimel/reveal.js/releases>
1100
1101 2. Unzip and replace the example contents in index.html with your own
1102
1103 3. Open index.html in a browser to view it
1104
1105
1106 ### Full setup
1107
1108 Some reveal.js features, like external Markdown and speaker notes, require that presentations run from a local web server. The following instructions will set up such a server as well as all of the development tasks needed to make edits to the reveal.js source code.
1109
1110 1. Install [Node.js](http://nodejs.org/) (1.0.0 or later)
1111
1112 1. Clone the reveal.js repository
1113    ```sh
1114    $ git clone https://github.com/hakimel/reveal.js.git
1115    ```
1116
1117 1. Navigate to the reveal.js folder
1118    ```sh
1119    $ cd reveal.js
1120    ```
1121
1122 1. Install dependencies
1123    ```sh
1124    $ npm install
1125    ```
1126
1127 1. Serve the presentation and monitor source files for changes
1128    ```sh
1129    $ npm start
1130    ```
1131
1132 1. Open <http://localhost:8000> to view your presentation
1133
1134    You can change the port by using `npm start -- --port 8001`.
1135
1136
1137 ### Folder Structure
1138 - **css/** Core styles without which the project does not function
1139 - **js/** Like above but for JavaScript
1140 - **plugin/** Components that have been developed as extensions to reveal.js
1141 - **lib/** All other third party assets (JavaScript, CSS, fonts)
1142
1143
1144 ## License
1145
1146 MIT licensed
1147
1148 Copyright (C) 2016 Hakim El Hattab, http://hakim.se