README.md 52.8 KB
Newer Older
Hakim El Hattab's avatar
Hakim El Hattab committed
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://revealjs.com/).
Hakim El Hattab's avatar
Hakim El Hattab committed
4

Hakim El Hattab's avatar
Hakim El Hattab committed
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).
Hakim El Hattab's avatar
Hakim El Hattab committed
6

7

Hakim El Hattab's avatar
Hakim El Hattab committed
8
## Table of contents
9

Hakim El Hattab's avatar
Hakim El Hattab committed
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
- [Online Editor](#online-editor)
- [Instructions](#instructions)
  - [Markup](#markup)
  - [Markdown](#markdown)
  - [Element Attributes](#element-attributes)
  - [Slide Attributes](#slide-attributes)
- [Configuration](#configuration)
- [Presentation Size](#presentation-size)
- [Dependencies](#dependencies)
- [Ready Event](#ready-event)
- [Auto-sliding](#auto-sliding)
- [Keyboard Bindings](#keyboard-bindings)
- [Touch Navigation](#touch-navigation)
- [Lazy Loading](#lazy-loading)
- [API](#api)
  - [Slide Changed Event](#slide-changed-event)
  - [Presentation State](#presentation-state)
  - [Slide States](#slide-states)
  - [Slide Backgrounds](#slide-backgrounds)
  - [Parallax Background](#parallax-background)
  - [Slide Transitions](#slide-transitions)
  - [Internal links](#internal-links)
  - [Fragments](#fragments)
  - [Fragment events](#fragment-events)
  - [Code syntax highlighting](#code-syntax-highlighting)
  - [Slide number](#slide-number)
  - [Overview mode](#overview-mode)
  - [Fullscreen mode](#fullscreen-mode)
  - [Embedded media](#embedded-media)
  - [Stretching elements](#stretching-elements)
  - [postMessage API](#postmessage-api)
- [PDF Export](#pdf-export)
- [Theming](#theming)
- [Speaker Notes](#speaker-notes)
  - [Share and Print Speaker Notes](#share-and-print-speaker-notes)
  - [Server Side Speaker Notes](#server-side-speaker-notes)
- [Multiplexing](#multiplexing)
  - [Master presentation](#master-presentation)
  - [Client presentation](#client-presentation)
  - [Socket.io server](#socketio-server)
- [MathJax](#mathjax)
- [Installation](#installation)
  - [Basic setup](#basic-setup)
  - [Full setup](#full-setup)
  - [Folder Structure](#folder-structure)
- [License](#license)
Hakim El Hattab's avatar
Hakim El Hattab committed
56

57
#### More reading
58

Hakim El Hattab's avatar
Hakim El Hattab committed
59
- [Changelog](https://github.com/hakimel/reveal.js/releases): Up-to-date version history.
Hakim El Hattab's avatar
Hakim El Hattab committed
60
- [Examples](https://github.com/hakimel/reveal.js/wiki/Example-Presentations): Presentations created with reveal.js, add your own!
Hansi's avatar
Hansi committed
61
- [Browser Support](https://github.com/hakimel/reveal.js/wiki/Browser-Support): Explanation of browser support and fallbacks.
Hakim El Hattab's avatar
Hakim El Hattab committed
62
- [Plugins](https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware): A list of plugins that can be used to extend reveal.js.
Hakim El Hattab's avatar
Hakim El Hattab committed
63

64

Hakim El Hattab's avatar
Hakim El Hattab committed
65
## Online Editor
Hakim El Hattab's avatar
Hakim El Hattab committed
66

Hakim El Hattab's avatar
Hakim El Hattab committed
67
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).
Hakim El Hattab's avatar
Hakim El Hattab committed
68 69


Hakim El Hattab's avatar
Hakim El Hattab committed
70
## Instructions
71

72
### Markup
73

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
Here's a barebones example of a fully working reveal.js presentation:
```html
<html>
	<head>
		<link rel="stylesheet" href="css/reveal.css">
		<link rel="stylesheet" href="css/theme/white.css">
	</head>
	<body>
		<div class="reveal">
			<div class="slides">
				<section>Slide 1</section>
				<section>Slide 2</section>
			</div>
		</div>
		<script src="js/reveal.js"></script>
		<script>
			Reveal.initialize();
		</script>
	</body>
</html>
```

Hakim El Hattab's avatar
Hakim El Hattab committed
96
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:
97

98
```html
99
<div class="reveal">
hakimel's avatar
hakimel committed
100
	<div class="slides">
101 102 103 104 105 106 107 108 109
		<section>Single Horizontal Slide</section>
		<section>
			<section>Vertical Slide 1</section>
			<section>Vertical Slide 2</section>
		</section>
	</div>
</div>
```

Hakim El Hattab's avatar
Hakim El Hattab committed
110 111
### Markdown

112
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 `<textarea data-template>` like the example below. You'll also need to add the `plugin/markdown/marked.js` and `plugin/markdown/markdown.js` scripts (in that order) to your HTML file.
Hakim El Hattab's avatar
Hakim El Hattab committed
113

114
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).
Hakim El Hattab's avatar
Hakim El Hattab committed
115 116 117

```html
<section data-markdown>
118
	<textarea data-template>
119
		## Page title
hakimel's avatar
hakimel committed
120

121
		A paragraph with some text and a [link](http://hakim.se).
122
	</textarea>
Hakim El Hattab's avatar
Hakim El Hattab committed
123 124 125
</section>
```

126 127
#### External Markdown

128
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-separator` attribute defines a regular expression for horizontal slides (defaults to `^\r?\n---\r?\n$`, a newline-bounded horizontal rule)  and `data-separator-vertical` defines vertical slides (disabled by default). The `data-separator-notes` attribute is a regular expression for specifying the beginning of the current slide's speaker notes (defaults to `notes?:`, so it will match both "note:" and "notes:"). The `data-charset` attribute is optional and specifies which charset to use when loading the external file.
129

130
When used locally, this feature requires that reveal.js [runs from a local web server](#full-setup).  The following example customises all available options:
131

132
```html
133 134 135 136
<section data-markdown="example.md"
         data-separator="^\n\n\n"
         data-separator-vertical="^\n\n"
         data-separator-notes="^Note:"
137
         data-charset="iso-8859-15">
138 139 140 141
    <!--
        Note that Windows uses `\r\n` instead of `\n` as its linefeed character.
        For a regex that supports all operating systems, use `\r?\n` instead of `\n`.
    -->
142
</section>
143 144
```

Hakim El Hattab's avatar
Hakim El Hattab committed
145 146
#### Element Attributes

147
Special syntax (through HTML comments) is available for adding attributes to Markdown elements. This is useful for fragments, amongst other things.
Hakim El Hattab's avatar
Hakim El Hattab committed
148 149 150 151

```html
<section data-markdown>
	<script type="text/template">
152 153
		- Item 1 <!-- .element: class="fragment" data-fragment-index="2" -->
		- Item 2 <!-- .element: class="fragment" data-fragment-index="1" -->
Hakim El Hattab's avatar
Hakim El Hattab committed
154 155 156 157
	</script>
</section>
```

Hakim El Hattab's avatar
Hakim El Hattab committed
158
#### Slide Attributes
Hakim El Hattab's avatar
Hakim El Hattab committed
159

160
Special syntax (through HTML comments) is available for adding attributes to the slide `<section>` elements generated by your Markdown.
Hakim El Hattab's avatar
Hakim El Hattab committed
161 162 163 164

```html
<section data-markdown>
	<script type="text/template">
Hakim El Hattab's avatar
Hakim El Hattab committed
165
	<!-- .slide: data-background="#ff0000" -->
Hakim El Hattab's avatar
Hakim El Hattab committed
166
		Markdown content
Hakim El Hattab's avatar
Hakim El Hattab committed
167 168 169 170
	</script>
</section>
```

Hakim El Hattab's avatar
Hakim El Hattab committed
171
#### Configuring *marked*
172 173 174 175 176 177 178 179 180 181 182

We use [marked](https://github.com/chjj/marked) to parse Markdown. To customise marked's rendering, you can pass in options when [configuring Reveal](#configuration):

```javascript
Reveal.initialize({
	// Options which are passed into marked
	// See https://github.com/chjj/marked#options-1
	markdown: {
		smartypants: true
	}
});
Hakim El Hattab's avatar
Hakim El Hattab committed
183
```
Hakim El Hattab's avatar
Hakim El Hattab committed
184

185 186
### Configuration

187
At the end of your page you need to initialize reveal by running the following code. Note that all configuration values are optional and will default to the values specified below.
188

189
```javascript
190
Reveal.initialize({
191

192
	// Display presentation control arrows
193 194
	controls: true,

195 196 197
	// Help the user learn the controls by providing hints, for example by
	// bouncing the down arrow when they first encounter a vertical slide
	controlsTutorial: true,
198 199 200 201 202 203 204 205

	// Determines where controls appear, "edges" or "bottom-right"
	controlsLayout: 'bottom-right',

	// Visibility rule for backwards navigation arrows; "faded", "hidden"
	// or "visible"
	controlsBackArrows: 'faded',

206 207 208
	// Display a presentation progress bar
	progress: true,

209 210 211
	// Display the page number of the current slide
	slideNumber: false,

212 213
	// Push each slide change to the browser history
	history: false,
214

215 216 217
	// Enable keyboard shortcuts for navigation
	keyboard: true,

218 219 220
	// Enable the slide overview mode
	overview: true,

221
	// Vertical centering of slides
222
	center: true,
223

224 225 226
	// Enables touch navigation on devices with touch input
	touch: true,

227
	// Loop the presentation
228 229
	loop: false,

Hakim El Hattab's avatar
Hakim El Hattab committed
230 231 232
	// Change the presentation direction to be RTL
	rtl: false,

233 234 235
	// Randomizes the order of slides each time the presentation loads
	shuffle: false,

236 237 238
	// Turns fragments on and off globally
	fragments: true,

239 240 241 242
	// Flags whether to include the current fragment in the URL,
	// so that reloading brings you to the same fragment position
	fragmentInURL: false,

243 244 245 246
	// Flags if the presentation is running in an embedded mode,
	// i.e. contained within a limited portion of the screen
	embedded: false,

Hakim El Hattab's avatar
Hakim El Hattab committed
247 248 249 250
	// Flags if we should show a help overlay when the questionmark
	// key is pressed
	help: true,

251 252 253
	// Flags if speaker notes should be visible to all viewers
	showNotes: false,

hoeggi's avatar
hoeggi committed
254
	// Global override for autoplaying embedded media (video/audio/iframe)
255 256 257 258 259
	// - null: Media will only autoplay if data-autoplay is present
	// - true: All media will autoplay, regardless of individual setting
	// - false: No media will autoplay, regardless of individual setting
	autoPlayMedia: null,

Hakim El Hattab's avatar
Hakim El Hattab committed
260
	// Number of milliseconds between automatically proceeding to the
261
	// next slide, disabled when set to 0, this value can be overwritten
262
	// by using a data-autoslide attribute on your slides
263 264
	autoSlide: 0,

265 266 267
	// Stop auto-sliding after user input
	autoSlideStoppable: true,

268 269
	// Use this method for navigation when auto-sliding
	autoSlideMethod: Reveal.navigateNext,
MichiK's avatar
MichiK committed
270

Hakim El Hattab's avatar
Hakim El Hattab committed
271 272 273 274 275
	// Specify the average time in seconds that you think you will spend
	// presenting each slide. This is used to show a pacing timer in the
	// speaker view
	defaultTiming: 120,

276
	// Enable slide navigation via mouse wheel
277
	mouseWheel: false,
278

279 280 281 282
	// Hides the address bar on mobile devices
	hideAddressBar: true,

	// Opens links in an iframe preview overlay
283 284
	// Add `data-preview-link` and `data-preview-link="false"` to customise each link
	// individually
285 286
	previewLinks: false,

287
	// Transition style
288
	transition: 'slide', // none/fade/slide/convex/concave/zoom
289 290 291

	// Transition speed
	transitionSpeed: 'default', // default/fast/slow
292

293
	// Transition style for full page slide backgrounds
294
	backgroundTransition: 'fade', // none/fade/slide/convex/concave/zoom
295 296

	// Number of slides away from the current that are visible
297
	viewDistance: 3,
298

299
	// Parallax background image
300
	parallaxBackgroundImage: '', // e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'"
301

302
	// Parallax background size
303
	parallaxBackgroundSize: '', // CSS syntax, e.g. "2100px 900px"
304

305 306 307 308
	// Number of pixels to move the parallax background per slide
	// - Calculated automatically unless specified
	// - Set to 0 to disable movement along an axis
	parallaxBackgroundHorizontal: null,
309 310 311 312
	parallaxBackgroundVertical: null,

	// The display mode that will be used to show slides
	display: 'block'
313

314 315 316
});
```

317
The configuration can be updated after initialization using the `configure` method:
318 319 320 321 322 323 324 325 326

```javascript
// Turn autoSlide off
Reveal.configure({ autoSlide: 0 });

// Start auto-sliding every 5s
Reveal.configure({ autoSlide: 5000 });
```

327 328
### Presentation Size

329
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.
330 331 332 333 334 335

See below for a list of configuration options related to sizing, including default values:

```javascript
Reveal.initialize({

336
	// ...
337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353

	// The "normal" size of the presentation, aspect ratio will be preserved
	// when the presentation is scaled to fit different resolutions. Can be
	// specified using percentage units.
	width: 960,
	height: 700,

	// Factor of the display size that should remain empty around the content
	margin: 0.1,

	// Bounds for smallest/largest possible scale to apply to content
	minScale: 0.2,
	maxScale: 1.5

});
```

354 355 356 357 358
If you wish to disable this behavior and do your own scaling (e.g. using media queries), try these settings:

```javascript
Reveal.initialize({

359
	// ...
360 361 362 363 364 365 366 367

	width: "100%",
	height: "100%",
	margin: 0,
	minScale: 1,
	maxScale: 1
});
```
368

Hakim El Hattab's avatar
Hakim El Hattab committed
369 370 371 372 373 374 375
### Dependencies

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:

```javascript
Reveal.initialize({
	dependencies: [
Hakim El Hattab's avatar
Hakim El Hattab committed
376
		// Cross-browser shim that fully implements classList - https://github.com/eligrey/classList.js/
377
		{ src: 'lib/js/classList.js', condition: function() { return !document.body.classList; } },
hakimel's avatar
hakimel committed
378

Hakim El Hattab's avatar
Hakim El Hattab committed
379
		// Interpret Markdown in <section> elements
380
		{ src: 'plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
381
		{ src: 'plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
hakimel's avatar
hakimel committed
382

383 384
		// Syntax highlight for <code> elements
		{ src: 'plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },
hakimel's avatar
hakimel committed
385

Dan Dascalescu's avatar
Dan Dascalescu committed
386
		// Zoom in and out with Alt+click
387
		{ src: 'plugin/zoom-js/zoom.js', async: true },
388

389
		// Speaker notes
390
		{ src: 'plugin/notes/notes.js', async: true },
391

Hakim El Hattab's avatar
Hakim El Hattab committed
392 393
		// MathJax
		{ src: 'plugin/math/math.js', async: true }
Hakim El Hattab's avatar
Hakim El Hattab committed
394 395 396 397 398 399 400 401 402 403
	]
});
```

You can add your own extensions using the same syntax. The following properties are available for each dependency object:
- **src**: Path to the script to load
- **async**: [optional] Flags if the script should load after reveal.js has started, defaults to false
- **callback**: [optional] Function to execute when the script has loaded
- **condition**: [optional] Function which must return true for the script to be loaded

404
To load these dependencies, reveal.js requires [head.js](http://headjs.com/) *(a script loading library)* to be loaded before reveal.js.
Hakim El Hattab's avatar
Hakim El Hattab committed
405

406 407
### Ready Event

408
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()`.
409 410 411 412 413 414 415

```javascript
Reveal.addEventListener( 'ready', function( event ) {
	// event.currentSlide, event.indexh, event.indexv
} );
```

416
Note that we also add a `.ready` class to the `.reveal` element so that you can hook into this with CSS.
417

418 419
### Auto-sliding

kayakr's avatar
kayakr committed
420
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:
421 422 423 424 425 426 427 428

```javascript
// Slide every five seconds
Reveal.configure({
  autoSlide: 5000
});
```

429 430 431
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.

You can also override the slide duration for individual slides and fragments by using the `data-autoslide` attribute:
432 433

```html
rajgoel's avatar
rajgoel committed
434 435 436 437 438
<section data-autoslide="2000">
	<p>After 2 seconds the first fragment will be shown.</p>
	<p class="fragment" data-autoslide="10000">After 10 seconds the next fragment will be shown.</p>
	<p class="fragment">Now, the fragment is displayed for 2 seconds before the next slide is shown.</p>
</section>
439 440
```

441
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`.
442

443
Whenever the auto-slide mode is resumed or paused the `autoslideresumed` and `autoslidepaused` events are fired.
444

445 446
### Keyboard Bindings

447
If you're unhappy with any of the default keyboard bindings you can override them using the `keyboard` config option:
448 449 450 451 452 453 454 455 456 457 458

```javascript
Reveal.configure({
  keyboard: {
    13: 'next', // go to the next slide when the ENTER key is pressed
    27: function() {}, // do something custom when ESC is pressed
    32: null // don't do anything when SPACE is pressed (i.e. disable a reveal.js default binding)
  }
});
```

459 460 461 462 463 464
### Touch Navigation

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.

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.

Hakim El Hattab's avatar
Hakim El Hattab committed
465 466
### Lazy Loading

467
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.
Hakim El Hattab's avatar
Hakim El Hattab committed
468

469
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.
Hakim El Hattab's avatar
Hakim El Hattab committed
470 471 472 473

```html
<section>
  <img data-src="image.png">
Hakim El Hattab's avatar
Hakim El Hattab committed
474
  <iframe data-src="http://hakim.se"></iframe>
Hakim El Hattab's avatar
Hakim El Hattab committed
475 476 477 478 479 480 481
  <video>
    <source data-src="video.webm" type="video/webm" />
    <source data-src="video.mp4" type="video/mp4" />
  </video>
</section>
```

482 483
### API

484
The `Reveal` object exposes a JavaScript API for controlling navigation and reading state:
485

Hakim El Hattab's avatar
Hakim El Hattab committed
486
```javascript
487
// Navigation
Federico Fissore's avatar
Federico Fissore committed
488
Reveal.slide( indexh, indexv, indexf );
489 490 491 492 493 494
Reveal.left();
Reveal.right();
Reveal.up();
Reveal.down();
Reveal.prev();
Reveal.next();
495 496
Reveal.prevFragment();
Reveal.nextFragment();
497

498 499 500
// Randomize the order of slides
Reveal.shuffle();

501
// Toggle presentation states, optionally pass true/false to force on/off
Hakim El Hattab's avatar
Hakim El Hattab committed
502
Reveal.toggleOverview();
Hakim El Hattab's avatar
Hakim El Hattab committed
503
Reveal.togglePause();
rajgoel's avatar
rajgoel committed
504
Reveal.toggleAutoSlide();
505

506 507 508 509
// Shows a help overlay with keyboard shortcuts, optionally pass true/false
// to force on/off
Reveal.toggleHelp();

510 511 512
// Change a config value at runtime
Reveal.configure({ controls: true });

513
// Returns the present configuration options
514 515 516 517 518
Reveal.getConfig();

// Fetch the current scale of the presentation
Reveal.getScale();

519 520 521 522
// Retrieves the previous and current slide elements
Reveal.getPreviousSlide();
Reveal.getCurrentSlide();

523 524
Reveal.getIndices();        // { h: 0, v: 0, f: 0 }
Reveal.getSlidePastCount();
Adam Spiers's avatar
Adam Spiers committed
525 526
Reveal.getProgress();       // (0 == first slide, 1 == last slide)
Reveal.getSlides();         // Array of all slides
527
Reveal.getTotalSlides();    // Total number of slides
Hakim El Hattab's avatar
Hakim El Hattab committed
528

529 530 531
// Returns the speaker notes for the current slide
Reveal.getSlideNotes();

Hakim El Hattab's avatar
Hakim El Hattab committed
532 533 534 535 536
// State checks
Reveal.isFirstSlide();
Reveal.isLastSlide();
Reveal.isOverview();
Reveal.isPaused();
537
Reveal.isAutoSliding();
Hakim El Hattab's avatar
Hakim El Hattab committed
538
```
539

540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570
### Custom Key Bindings

Custom key bindings can be added and removed using the following Javascript API. Custom key bindings will override the default keyboard bindings, but will in turn be overridden by the user defined bindings in the ``keyboard`` config option.

```javascript
Reveal.addKeyBinding( binding, callback );
Reveal.removeKeyBinding( keyCode );
```

For example

```javascript
// The binding parameter provides the following properties
//      keyCode: the keycode for binding to the callback
//          key: the key label to show in the help overlay
//  description: the description of the action to show in the help overlay
Reveal.addKeyBinding( { keyCode: 84, key: 'T', description: 'Start timer' }, function() {
	// start timer
} )

// The binding parameter can also be a direct keycode without providing the help description
Reveal.addKeyBinding( 82, function() {
	// reset timer
} )
```

This allows plugins to add key bindings directly to Reveal so they can

* make use of Reveal's pre-processing logic for key handling (for example, ignoring key presses when paused); and
* be included in the help overlay (optional)

571
### Slide Changed Event
572

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

Hakim El Hattab's avatar
Hakim El Hattab committed
575 576
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.

577
```javascript
578
Reveal.addEventListener( 'slidechanged', function( event ) {
579
	// event.previousSlide, event.currentSlide, event.indexh, event.indexv
580 581 582
} );
```

583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600
### Presentation State

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.

```javascript
Reveal.slide( 1 );
// we're on slide 1

var state = Reveal.getState();

Reveal.slide( 3 );
// we're on slide 3

Reveal.setState( state );
// we're back on slide 1
```

### Slide States
601

602
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.
603 604 605 606 607 608 609 610 611 612

Furthermore you can also listen to these changes in state via JavaScript:

```javascript
Reveal.addEventListener( 'somestate', function() {
	// TODO: Sprinkle magic
}, false );
```

### Slide Backgrounds
613

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

616
#### Color Backgrounds
617 618 619

All CSS color formats are supported, including hex values, keywords, `rgba()` or `hsl()`.

620
```html
Hakim El Hattab's avatar
Hakim El Hattab committed
621 622
<section data-background-color="#ff0000">
	<h2>Color</h2>
623
</section>
Hakim El Hattab's avatar
Hakim El Hattab committed
624 625
```

626
#### Image Backgrounds
627

Hakim El Hattab's avatar
Hakim El Hattab committed
628 629
By default, background images are resized to cover the full page. Available options:

630 631 632 633 634 635
| Attribute                        | Default    | Description |
| :------------------------------- | :--------- | :---------- |
| data-background-image            |            | URL of the image to show. GIFs restart when the slide opens. |
| data-background-size             | cover      | See [background-size](https://developer.mozilla.org/docs/Web/CSS/background-size) on MDN.  |
| data-background-position         | center     | See [background-position](https://developer.mozilla.org/docs/Web/CSS/background-position) on MDN. |
| data-background-repeat           | no-repeat  | See [background-repeat](https://developer.mozilla.org/docs/Web/CSS/background-repeat) on MDN. |
636
| data-background-opacity          | 1          | Opacity of the background image on a 0-1 scale. 0 is transparent and 1 is fully opaque. |
637

Hakim El Hattab's avatar
Hakim El Hattab committed
638 639 640
```html
<section data-background-image="http://example.com/image.png">
	<h2>Image</h2>
641
</section>
Hakim El Hattab's avatar
Hakim El Hattab committed
642 643
<section data-background-image="http://example.com/image.png" data-background-size="100px" data-background-repeat="repeat">
	<h2>This background image will be sized to 100px and repeated</h2>
644
</section>
Hakim El Hattab's avatar
Hakim El Hattab committed
645 646
```

647
#### Video Backgrounds
648

Hakim El Hattab's avatar
Hakim El Hattab committed
649 650
Automatically plays a full size video behind the slide.

651 652 653 654 655 656
| Attribute                        | Default | Description |
| :---------------------------     | :------ | :---------- |
| data-background-video            |         | A single video source, or a comma separated list of video sources. |
| data-background-video-loop       | false   | Flags if the video should play repeatedly. |
| data-background-video-muted      | false   | Flags if the audio should be muted. |
| data-background-size             | cover   | Use `cover` for full screen and some cropping or `contain` for letterboxing. |
657
| data-background-opacity          | 1       | Opacity of the background video on a 0-1 scale. 0 is transparent and 1 is fully opaque. |
Hakim El Hattab's avatar
Hakim El Hattab committed
658 659

```html
660
<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>
Hakim El Hattab's avatar
Hakim El Hattab committed
661
	<h2>Video</h2>
662
</section>
Hakim El Hattab's avatar
Hakim El Hattab committed
663 664
```

665
#### Iframe Backgrounds
666

Hakim El Hattab's avatar
Hakim El Hattab committed
667
Embeds a web page as a slide background that covers 100% of the reveal.js width and height. The iframe is in the background layer, behind your slides, and as such it's not possible to interact with it by default. To make your background interactive, you can add the `data-background-interactive` attribute.
668

Hakim El Hattab's avatar
Hakim El Hattab committed
669
```html
Hakim El Hattab's avatar
Hakim El Hattab committed
670
<section data-background-iframe="https://slides.com" data-background-interactive>
Hakim El Hattab's avatar
Hakim El Hattab committed
671
	<h2>Iframe</h2>
672
</section>
673 674
```

675
#### Background Transitions
676 677

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

679

680 681
### Parallax Background

682
If you want to use a parallax scrolling background, set the first two properties below when initializing reveal.js (the other two are optional).
683 684 685

```javascript
Reveal.initialize({
686

687
	// Parallax background image
688
	parallaxBackgroundImage: '', // e.g. "https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg"
689

690
	// Parallax background size
691
	parallaxBackgroundSize: '', // CSS syntax, e.g. "2100px 900px" - currently only pixels are supported (don't use % or auto)
692

693 694 695
	// Number of pixels to move the parallax background per slide
	// - Calculated automatically unless specified
	// - Set to 0 to disable movement along an axis
696 697
	parallaxBackgroundHorizontal: 200,
	parallaxBackgroundVertical: 50
698 699 700 701

});
```

702
Make sure that the background size is much bigger than screen size to allow for some scrolling. [View example](http://revealjs.com/?parallaxBackgroundImage=https%3A%2F%2Fs3.amazonaws.com%2Fhakim-static%2Freveal-js%2Freveal-parallax-1.jpg&parallaxBackgroundSize=2100px%20900px).
703

704
### Slide Transitions
705 706

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:
Hakim El Hattab's avatar
Hakim El Hattab committed
707

708 709 710 711
```html
<section data-transition="zoom">
	<h2>This slide will override the presentation transition and zoom!</h2>
</section>
Hakim El Hattab's avatar
Hakim El Hattab committed
712

713 714 715
<section data-transition-speed="fast">
	<h2>Choose from three transition speeds: default, fast or slow!</h2>
</section>
Hakim El Hattab's avatar
Hakim El Hattab committed
716 717
```

718
You can also use different in and out transitions for the same slide:
Johannes Ammon's avatar
Johannes Ammon committed
719 720 721

```html
<section data-transition="slide">
722
    The train goes on …
Johannes Ammon's avatar
Johannes Ammon committed
723
</section>
724 725
<section data-transition="slide">
    and on …
Johannes Ammon's avatar
Johannes Ammon committed
726
</section>
727
<section data-transition="slide-in fade-out">
Johannes Ammon's avatar
Johannes Ammon committed
728 729
    and stops.
</section>
730
<section data-transition="fade-in slide-out">
Johannes Ammon's avatar
Johannes Ammon committed
731 732 733 734 735 736
    (Passengers entering and leaving)
</section>
<section data-transition="slide">
    And it starts again.
</section>
```
737
You can choose from `none`, `fade`, `slide`, `convex`, `concave` and `zoom`.
Hakim El Hattab's avatar
Hakim El Hattab committed
738 739
### Internal links

740
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">`):
Hakim El Hattab's avatar
Hakim El Hattab committed
741 742 743 744 745

```html
<a href="#/2/2">Link</a>
<a href="#/some-slide">Link</a>
```
746

747
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.
748 749 750 751 752 753

```html
<a href="#" class="navigate-left">
<a href="#" class="navigate-right">
<a href="#" class="navigate-up">
<a href="#" class="navigate-down">
Hakim El Hattab's avatar
Hakim El Hattab committed
754
<a href="#" class="navigate-prev"> <!-- Previous vertical or horizontal slide -->
755 756 757
<a href="#" class="navigate-next"> <!-- Next vertical or horizontal slide -->
```

Hakim El Hattab's avatar
Hakim El Hattab committed
758
### Fragments
759 760

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://revealjs.com/#/fragments
Hakim El Hattab's avatar
Hakim El Hattab committed
761 762 763 764 765 766 767 768

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:

```html
<section>
	<p class="fragment grow">grow</p>
	<p class="fragment shrink">shrink</p>
	<p class="fragment fade-out">fade-out</p>
769
	<p class="fragment fade-up">fade-up (also down, left and right!)</p>
770
	<p class="fragment fade-in-then-out">fades in, then out when we move to the next step</p>
Hakim El Hattab's avatar
Hakim El Hattab committed
771
	<p class="fragment fade-in-then-semi-out">fades in, then obfuscate when we move to the next step</p>
772
	<p class="fragment highlight-current-blue">blue only once</p>
Hakim El Hattab's avatar
Hakim El Hattab committed
773 774 775 776 777 778
	<p class="fragment highlight-red">highlight-red</p>
	<p class="fragment highlight-green">highlight-green</p>
	<p class="fragment highlight-blue">highlight-blue</p>
</section>
```

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

Hakim El Hattab's avatar
Hakim El Hattab committed
781
```html
782
<section>
783
	<span class="fragment fade-in">
784 785 786 787 788
		<span class="fragment fade-out">I'll fade in, then out</span>
	</span>
</section>
```

789
The display order of fragments can be controlled using the `data-fragment-index` attribute.
790 791 792 793 794 795 796 797 798

```html
<section>
	<p class="fragment" data-fragment-index="3">Appears last</p>
	<p class="fragment" data-fragment-index="1">Appears first</p>
	<p class="fragment" data-fragment-index="2">Appears second</p>
</section>
```

799 800 801 802
### Fragment events

When a slide fragment is either shown or hidden reveal.js will dispatch an event.

Hakim El Hattab's avatar
Hakim El Hattab committed
803 804
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.

805
```javascript
806 807 808 809 810 811 812 813
Reveal.addEventListener( 'fragmentshown', function( event ) {
	// event.fragment = the fragment DOM element
} );
Reveal.addEventListener( 'fragmenthidden', function( event ) {
	// event.fragment = the fragment DOM element
} );
```

wtw's avatar
wtw committed
814
### Code syntax highlighting
815

816 817
By default, Reveal is configured with [highlight.js](https://highlightjs.org/) for code syntax highlighting. To enable syntax highlighting, you'll have to load the highlight plugin ([plugin/highlight/highlight.js](plugin/highlight/highlight.js)) and a highlight.js CSS theme (Reveal comes packaged with the zenburn theme: [lib/css/zenburn.css](lib/css/zenburn.css)).

818 819 820 821 822 823 824 825 826
```javascript
Reveal.initialize({
	// More info https://github.com/hakimel/reveal.js#dependencies
	dependencies: [
		{ src: 'plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } },
	]
});
```

827
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.
828 829 830

```html
<section>
831
	<pre><code data-trim data-noescape>
832 833 834
(def lazy-fib
  (concat
   [0 1]
835
   <mark>((fn rfib [a b]</mark>
836
        (lazy-cons (+ a b) (rfib b (+ a b)))) 0 1)))
837
	</code></pre>
838 839 840
</section>
```

841
### Slide number
842 843

If you would like to display the page number of the current slide you can do so using the `slideNumber` and `showSlideNumber` configuration values.
844 845

```javascript
846
// Shows the slide number using default formatting
847
Reveal.configure({ slideNumber: true });
848 849

// Slide number formatting can be configured using these variables:
Hakim El Hattab's avatar
Hakim El Hattab committed
850 851
//  "h.v": 	horizontal . vertical slide number (default)
//  "h/v": 	horizontal / vertical slide number
Hakim El Hattab's avatar
Hakim El Hattab committed
852 853 854
//    "c": 	flattened slide number
//  "c/t": 	flattened slide number / total slides
Reveal.configure({ slideNumber: 'c/t' });
855

856 857 858 859 860
// Control which views the slide number displays on using the "showSlideNumber" value:
//     "all": show on all views (default)
// "speaker": only show slide numbers on speaker notes view
//   "print": only show slide numbers when printing to PDF
Reveal.configure({ showSlideNumber: 'speaker' });
861 862
```

Hakim El Hattab's avatar
Hakim El Hattab committed
863 864
### Overview mode

865
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,
866 867 868 869 870 871 872 873 874
as if you were at 1,000 feet above your presentation. The overview mode comes with a few API hooks:

```javascript
Reveal.addEventListener( 'overviewshown', function( event ) { /* ... */ } );
Reveal.addEventListener( 'overviewhidden', function( event ) { /* ... */ } );

// Toggle the overview mode programmatically
Reveal.toggleOverview();
```
Hakim El Hattab's avatar
Hakim El Hattab committed
875 876 877

### Fullscreen mode

878
Just press »F« on your keyboard to show your presentation in fullscreen mode. Press the »ESC« key to exit fullscreen mode.
879

Hakim El Hattab's avatar
Hakim El Hattab committed
880
### Embedded media
881

Hakim El Hattab's avatar
Hakim El Hattab committed
882 883 884
Add `data-autoplay` to your media element if you want it to automatically start playing when the slide is shown:

```html
Hakim El Hattab's avatar
Hakim El Hattab committed
885
<video data-autoplay src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4"></video>
Hakim El Hattab's avatar
Hakim El Hattab committed
886 887
```

888 889 890 891 892 893
If you want to enable or disable autoplay globally, for all embedded media, you can use the `autoPlayMedia` configuration option. If you set this to `true` ALL media will autoplay regardless of individual `data-autoplay` attributes. If you initialize with `autoPlayMedia: false` NO media will autoplay.

Note that embedded HTML5 `<video>`/`<audio>` and YouTube/Vimeo iframes are automatically paused when you navigate away from a slide. This can be disabled by decorating your element with a `data-ignore` attribute.

### Embedded iframes

894
reveal.js automatically pushes two [post messages](https://developer.mozilla.org/en-US/docs/Web/API/Window.postMessage) to embedded iframes. `slide:start` when the slide containing the iframe is made visible and `slide:stop` when it is hidden.
Hakim El Hattab's avatar
Hakim El Hattab committed
895

Hakim El Hattab's avatar
Hakim El Hattab committed
896
### Stretching elements
897 898

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:
Hakim El Hattab's avatar
Hakim El Hattab committed
899 900 901 902 903 904 905 906 907

```html
<section>
	<h2>This video will use up the remaining space on the slide</h2>
    <video class="stretch" src="http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4"></video>
</section>
```

Limitations:
Hakim El Hattab's avatar
Hakim El Hattab committed
908 909
- Only direct descendants of a slide section can be stretched
- Only one descendant per slide section can be stretched
Hakim El Hattab's avatar
Hakim El Hattab committed
910

911
### postMessage API
912

913 914 915 916 917 918 919 920 921 922 923
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:

```javascript
<window>.postMessage( JSON.stringify({ method: 'slide', args: [ 2 ] }), '*' );
```

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:

```javascript
window.addEventListener( 'message', function( event ) {
	var data = JSON.parse( event.data );
924
	if( data.namespace === 'reveal' && data.eventName ==='slidechanged' ) {