files/reveal.js/README.md in reveal-ck-3.9.2 vs files/reveal.js/README.md in reveal-ck-4.0.0

- old
+ new

@@ -1,15 +1,22 @@ # 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> -A framework for easily creating beautiful presentations using HTML. [Check out the live demo](http://revealjs.com/). +A framework for easily creating beautiful presentations using HTML. [Check out the live demo](https://revealjs.com/). -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). +reveal.js comes with a broad range of features including [nested slides](https://github.com/hakimel/reveal.js#markup), [Markdown support](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). +### Supporting reveal.js +This project was started and is maintained by [@hakimel](https://github.com/hakimel/) with the help of many [contributions from the community](https://github.com/hakimel/reveal.js/graphs/contributors). The best way to support the project is to [become a paying member of Slides.com](https://slides.com/pricing)—the reveal.js presentation platform that Hakim is building. + ## Table of contents - [Online Editor](#online-editor) +- [Installation](#installation) + - [Basic setup](#basic-setup) + - [Full setup](#full-setup) + - [Folder Structure](#folder-structure) - [Instructions](#instructions) - [Markup](#markup) - [Markdown](#markdown) - [Element Attributes](#element-attributes) - [Slide Attributes](#slide-attributes) @@ -17,13 +24,15 @@ - [Presentation Size](#presentation-size) - [Dependencies](#dependencies) - [Ready Event](#ready-event) - [Auto-sliding](#auto-sliding) - [Keyboard Bindings](#keyboard-bindings) +- [Vertical Slide Navigation](#vertical-slide-navigation) - [Touch Navigation](#touch-navigation) - [Lazy Loading](#lazy-loading) - [API](#api) + - [Custom Key Bindings](#custom-key-bindings) - [Slide Changed Event](#slide-changed-event) - [Presentation State](#presentation-state) - [Slide States](#slide-states) - [Slide Backgrounds](#slide-backgrounds) - [Parallax Background](#parallax-background) @@ -35,25 +44,23 @@ - [Slide number](#slide-number) - [Overview mode](#overview-mode) - [Fullscreen mode](#fullscreen-mode) - [Embedded media](#embedded-media) - [Stretching elements](#stretching-elements) + - [Resize Event](#resize-event) - [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) +- [Plugins](#plugins) - [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) #### More reading - [Changelog](https://github.com/hakimel/reveal.js/releases): Up-to-date version history. @@ -65,10 +72,60 @@ ## Online Editor 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). +## Installation + +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. + +### Basic setup + +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. + +1. Download the latest version of reveal.js from <https://github.com/hakimel/reveal.js/releases> +2. Unzip and replace the example contents in index.html with your own +3. Open index.html in a browser to view it + +### Full setup + +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. + +1. Install [Node.js](https://nodejs.org/) (9.0.0 or later) + +1. Clone the reveal.js repository + ```sh + $ git clone https://github.com/hakimel/reveal.js.git + ``` + +1. Navigate to the reveal.js folder + ```sh + $ cd reveal.js + ``` + +1. Install dependencies + ```sh + $ npm install + ``` + +1. Serve the presentation and monitor source files for changes + ```sh + $ npm start + ``` + +1. Open <http://localhost:8000> to view your presentation + + You can change the port by using `npm start -- --port=8001`. + +### Folder Structure + +- **css/** Core styles without which the project does not function +- **js/** Like above but for JavaScript +- **plugin/** Components that have been developed as extensions to reveal.js +- **lib/** All other third party assets (JavaScript, CSS, fonts) + + ## Instructions ### Markup Here's a barebones example of a fully working reveal.js presentation: @@ -173,11 +230,11 @@ 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 + // See https://marked.js.org/#/USING_ADVANCED.md#options markdown: { smartypants: true } }); ``` @@ -207,11 +264,15 @@ progress: true, // Display the page number of the current slide slideNumber: false, - // Push each slide change to the browser history + // Add the current slide number to the URL hash so that reloading the + // page/copying the URL will return you to the same slide + hash: false, + + // Push each slide change to the browser history. Implies `hash: true` history: false, // Enable keyboard shortcuts for navigation keyboard: true, @@ -228,10 +289,13 @@ loop: false, // Change the presentation direction to be RTL rtl: false, + // See https://github.com/hakimel/reveal.js/#navigation-mode + navigationMode: 'default', + // Randomizes the order of slides each time the presentation loads shuffle: false, // Turns fragments on and off globally fragments: true, @@ -255,10 +319,17 @@ // - 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, + // Global override for preloading lazy-loaded iframes + // - null: Iframes with data-src AND data-preload will be loaded when within + // the viewDistance, iframes with only data-src will be loaded when visible + // - true: All iframes with data-src will be loaded when within the viewDistance + // - false: All iframes with data-src will be loaded only when visible + preloadIframes: null, + // Number of milliseconds between automatically proceeding to the // next slide, disabled when set to 0, this value can be overwritten // by using a data-autoslide attribute on your slides autoSlide: 0, @@ -271,13 +342,32 @@ // 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, + // Specify the total time in seconds that is available to + // present. If this is set to a nonzero value, the pacing + // timer will work out the time available for each slide, + // instead of using the defaultTiming value + totalTime: 0, + + // Specify the minimum amount of time you want to allot to + // each slide, if using the totalTime calculation method. If + // the automated time allocation causes slide pacing to fall + // below this threshold, then you will see an alert in the + // speaker notes window + minimumTimePerSlide: 0; + // Enable slide navigation via mouse wheel mouseWheel: false, + // Hide cursor if inactive + hideInactiveCursor: true, + + // Time before the cursor is hidden (in ms) + hideCursorTime: 5000, + // Hides the address bar on mobile devices hideAddressBar: true, // Opens links in an iframe preview overlay // Add `data-preview-link` and `data-preview-link="false"` to customise each link @@ -294,10 +384,15 @@ backgroundTransition: 'fade', // none/fade/slide/convex/concave/zoom // Number of slides away from the current that are visible viewDistance: 3, + // Number of slides away from the current that are visible on mobile + // devices. It is advisable to set this to a lower number than + // viewDistance in order to save resources. + mobileViewDistance: 2, + // Parallax background image parallaxBackgroundImage: '', // e.g. "'https://s3.amazonaws.com/hakim-static/reveal-js/reveal-parallax-1.jpg'" // Parallax background size parallaxBackgroundSize: '', // CSS syntax, e.g. "2100px 900px" @@ -371,19 +466,16 @@ 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: [ - // Cross-browser shim that fully implements classList - https://github.com/eligrey/classList.js/ - { src: 'lib/js/classList.js', condition: function() { return !document.body.classList; } }, - // Interpret Markdown in <section> elements { src: 'plugin/markdown/marked.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } }, { src: 'plugin/markdown/markdown.js', condition: function() { return !!document.querySelector( '[data-markdown]' ); } }, // Syntax highlight for <code> elements - { src: 'plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } }, + { src: 'plugin/highlight/highlight.js', async: true }, // Zoom in and out with Alt+click { src: 'plugin/zoom-js/zoom.js', async: true }, // Speaker notes @@ -399,12 +491,10 @@ - **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 -To load these dependencies, reveal.js requires [head.js](http://headjs.com/) *(a script loading library)* to be loaded before reveal.js. - ### Ready Event 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()`. ```javascript @@ -454,21 +544,36 @@ 32: null // don't do anything when SPACE is pressed (i.e. disable a reveal.js default binding) } }); ``` +### Vertical Slide Navigation + +Slides can be nested within other slides to create vertical stacks (see [Markup](#markup)). When presenting, you use the left/right arrows to step through the main (horizontal) slides. When you arrive at a vertical stack you can optionally press the up/down arrows to view the vertical slides or skip past them by pressing the right arrow. Here's an example showing a bird's-eye view of what this looks like in action: + +<img src="https://static.slid.es/support/reveal.js-vertical-slides.gif" width="450"> + +#### Navigation Mode +You can fine tune the reveal.js navigation behavior by using the `navigationMode` config option. Note that these options are only useful for presentations that use a mix of horizontal and vertical slides. The following navigation modes are available: + +| Value | Description | +| :--------------------------- | :---------- | +| default | Left/right arrow keys step between horizontal slides. Up/down arrow keys step between vertical slides. Space key steps through all slides (both horizontal and vertical). | +| linear | Removes the up/down arrows. Left/right arrows step through all slides (both horizontal and vertical). | +| grid | When this is enabled, stepping left/right from a vertical stack to an adjacent vertical stack will land you at the same vertical index.<br><br>Consider a deck with six slides ordered in two vertical stacks:<br>`1.1`&nbsp;&nbsp;&nbsp;&nbsp;`2.1`<br>`1.2`&nbsp;&nbsp;&nbsp;&nbsp;`2.2`<br>`1.3`&nbsp;&nbsp;&nbsp;&nbsp;`2.3`<br><br>If you're on slide 1.3 and navigate right, you will normally move from 1.3 -> 2.1. With navigationMode set to "grid" the same navigation takes you from 1.3 -> 2.3. | + ### 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. ### Lazy Loading 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. -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. +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. ```html <section> <img data-src="image.png"> <iframe data-src="http://hakim.se"></iframe> @@ -477,10 +582,30 @@ <source data-src="video.mp4" type="video/mp4" /> </video> </section> ``` +#### Lazy Loading Iframes + +Note that lazy loaded iframes ignore the `viewDistance` configuration and will only load when their containing slide becomes visible. Iframes are also unloaded as soon as the slide is hidden. + +When we lazy load a video or audio element, reveal.js won't start playing that content until the slide becomes visible. However there is no way to control this for an iframe since that could contain any kind of content. That means if we loaded an iframe before the slide is visible on screen it could begin playing media and sound in the background. + +You can override this behavior with the `data-preload` attribute. The iframe below will be loaded +according to the `viewDistance`. + +```html +<section> + <iframe data-src="http://hakim.se" data-preload></iframe> +</section> +``` + +You can also change the default globally with the `preloadIframes` configuration option. If set to +`true` ALL iframes with a `data-src` attribute will be preloaded when within the `viewDistance` +regardless of individual `data-preload` attributes. If set to `false`, all iframes will only be +loaded when they become visible. + ### API The `Reveal` object exposes a JavaScript API for controlling navigation and reading state: ```javascript @@ -524,19 +649,31 @@ Reveal.getSlidePastCount(); Reveal.getProgress(); // (0 == first slide, 1 == last slide) Reveal.getSlides(); // Array of all slides Reveal.getTotalSlides(); // Total number of slides +// Returns an array with all horizontal/vertical slides in the deck +Reveal.getHorizontalSlides(); +Reveal.getVerticalSlides(); + +// Checks if the presentation contains two or more +// horizontal/vertical slides +Reveal.hasHorizontalSlides(); +Reveal.hasVerticalSlides(); + // Returns the speaker notes for the current slide Reveal.getSlideNotes(); // State checks Reveal.isFirstSlide(); Reveal.isLastSlide(); Reveal.isOverview(); Reveal.isPaused(); Reveal.isAutoSliding(); + +// Returns the top-level DOM element +Reveal.getRevealElement(); // <div class="reveal">...</div> ``` ### 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. @@ -670,10 +807,12 @@ <section data-background-iframe="https://slides.com" data-background-interactive> <h2>Iframe</h2> </section> ``` +Iframes are lazy-loaded when they become visible. If you'd like to preload iframes ahead of time, you can append a `data-preload` attribute to the slide `<section>`. You can also enable preloading globally for all iframes using the `preloadIframes` configuration option. + #### Background Transitions 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. @@ -809,19 +948,19 @@ Reveal.addEventListener( 'fragmenthidden', function( event ) { // event.fragment = the fragment DOM element } ); ``` -### Code syntax highlighting +### Code Syntax Highlighting -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)). +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 Monokai themes: [lib/css/monokai.css](lib/css/monokai.css)). ```javascript Reveal.initialize({ // More info https://github.com/hakimel/reveal.js#dependencies dependencies: [ - { src: 'plugin/highlight/highlight.js', async: true, callback: function() { hljs.initHighlightingOnLoad(); } }, + { src: 'plugin/highlight/highlight.js', async: true }, ] }); ``` 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. @@ -836,10 +975,41 @@ (lazy-cons (+ a b) (rfib b (+ a b)))) 0 1))) </code></pre> </section> ``` +#### Line Numbers & Highlights + +To enable line numbers, add `data-line-numbers` to your `<code>` tags. If you want to highlight specific lines you can provide a comma separated list of line numbers using the same attribute. For example, in the following example lines 4 and 8-11 are highlighted: + +```html +<pre><code class="hljs" data-line-numbers="4,8-11"> +import React, { useState } from 'react'; + +function Example() { + const [count, setCount] = useState(0); + + return ( + <div> + <p>You clicked {count} times</p> + <button onClick={() => setCount(count + 1)}> + Click me + </button> + </div> + ); +} +</code></pre> +``` + +<img width="300" alt="line-numbers" src="https://user-images.githubusercontent.com/629429/55332077-eb3c4780-5494-11e9-8854-ba33cd0fa740.png"> + +#### Step-by-step Highlights + +You can step through multiple code highlights on the same code block. Delimit each of your highlight steps with the `|` character. For example `data-line-numbers="1|2-3|4,6-10"` will produce three steps. It will start by highlighting line 1, next step is lines 2-3, and finally line 4 and 6 through 10. + + + ### Slide number If you would like to display the page number of the current slide you can do so using the `slideNumber` and `showSlideNumber` configuration values. ```javascript @@ -851,10 +1021,16 @@ // "h/v": horizontal / vertical slide number // "c": flattened slide number // "c/t": flattened slide number / total slides Reveal.configure({ slideNumber: 'c/t' }); +// You can provide a function to fully customize the number: +Reveal.configure({ slideNumber: function( slide ) { + // Ignore numbering of vertical slides + return [ Reveal.getIndices( slide ).h ]; +}}); + // 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' }); @@ -906,32 +1082,62 @@ Limitations: - Only direct descendants of a slide section can be stretched - Only one descendant per slide section can be stretched +### Resize Event + +When reveal.js changes the scale of the slides it fires a resize event. You can subscribe to the event to resize your elements accordingly. + +```javascript +Reveal.addEventListener( 'resize', function( event ) { + // event.scale, event.oldScale, event.size +} ); +``` + ### postMessage API 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 ] }), '*' ); ``` +#### postMessage Events + 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 ); - if( data.namespace === 'reveal' && data.eventName ==='slidechanged' ) { + if( data.namespace === 'reveal' && data.eventName === 'slidechanged' ) { // Slide changed, see data.state for slide number } } ); ``` -This cross-window messaging can be toggled on or off using configuration flags. +#### postMessage Callbacks +When you call any method via the postMessage API, reveal.js will dispatch a message with the return value. This is done so that you can call a getter method and see what the result is. Check out this example: + ```javascript +<revealWindow>.postMessage( JSON.stringify({ method: 'getTotalSlides' }), '*' ); + +window.addEventListener( 'message', function( event ) { + var data = JSON.parse( event.data ); + // `data.method`` is the method that we invoked + if( data.namespace === 'reveal' && data.eventName === 'callback' && data.method === 'getTotalSlides' ) { + data.result // = the total number of slides + } +} ); +``` + +#### Turning postMessage on/off + +This cross-window messaging can be toggled on or off using configuration flags. These are the default values. + +```javascript Reveal.initialize({ // ... // Exposes the reveal.js API through window.postMessage postMessage: true, @@ -942,11 +1148,11 @@ ``` ## PDF Export -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) and to be serving the presentation from a webserver. +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) and to be serving the presentation from a web server. Here's an example of an exported presentation that's been uploaded to SlideShare: http://www.slideshare.net/hakimel/revealjs-300. ### Separate pages for fragments [Fragments](#fragments) are printed on separate slides by default. Meaning if you have a slide with three fragment steps, it will generate three separate slides where the fragments appear incrementally. @@ -1047,21 +1253,21 @@ #### Share and Print Speaker Notes 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` configuration value set to `true`. Notes will appear along the bottom of the presentations. -When `showNotes` is enabled notes are also included when you [export to PDF](https://github.com/hakimel/reveal.js#pdf-export). By default, notes are printed in a semi-transparent box on top of the slide. If you'd rather print them on a separate page after the slide, set `showNotes: "separate-page"`. +When `showNotes` is enabled notes are also included when you [export to PDF](https://github.com/hakimel/reveal.js#pdf-export). By default, notes are printed in a box on top of the slide. If you'd rather print them on a separate page, after the slide, set `showNotes: "separate-page"`. #### Speaker notes clock and timers The speaker notes window will also show: - Time elapsed since the beginning of the presentation. If you hover the mouse above this section, a timer reset button will appear. - Current wall-clock time - (Optionally) a pacing timer which indicates whether the current pace of the presentation is on track for the right timing (shown in green), and if not, whether the presenter should speed up (shown in red) or has the luxury of slowing down (blue). -The pacing timer can be enabled by configuring by the `defaultTiming` parameter in the `Reveal` configuration block, which specifies the number of seconds per slide. 120 can be a reasonable rule of thumb. Timings can also be given per slide `<section>` by setting the `data-timing` attribute. Both values are in numbers of seconds. +The pacing timer can be enabled by configuring the `defaultTiming` parameter in the `Reveal` configuration block, which specifies the number of seconds per slide. 120 can be a reasonable rule of thumb. Alternatively, you can enable the timer by setting `totalTime`, which sets the total length of your presentation (also in seconds). If both values are specified, `totalTime` wins and `defaultTiming` is ignored. Regardless of the baseline timing method, timings can also be given per slide `<section>` by setting the `data-timing` attribute (again, in seconds). ## Server Side Speaker Notes 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: @@ -1077,15 +1283,37 @@ }); ``` Then: -1. Install [Node.js](http://nodejs.org/) (4.0.0 or later) +1. Install [Node.js](http://nodejs.org/) (9.0.0 or later) 2. Run `npm install` 3. Run `node plugin/notes-server` +## Plugins + +Plugins should register themselves with reveal.js by calling `Reveal.registerPlugin( 'myPluginID', MyPlugin )`. Registered plugin instances can optionally expose an "init" function that reveal.js will call to initialize them. + +When reveal.js is booted up via `Reveal.initialize()`, it will go through all registered plugins and invoke their "init" methods. If the "init" method returns a Promise, reveal.js will wait for that promise to be fulfilled before finishing the startup sequence and firing the [ready](#ready-event) event. Here's an example of a plugin that does some asynchronous work before reveal.js can proceed: + +```javascript +let MyPlugin = { + init: () => new Promise( resolve => setTimeout( resolve, 3000 ) ) +}; +Reveal.registerPlugin( 'myPlugin', MyPlugin ); +Reveal.addEventListener( 'ready', () => console.log( 'Three seconds later...' ) ); +Reveal.initialize(); +``` + +Note that reveal.js will *not* wait for init Promise fulfillment if the plugin is loaded as an [async dependency](#dependencies). If the plugin's init method does _not_ return a Promise, the plugin is considered ready right away and will not hold up the reveal.js startup sequence. + +### Retrieving Plugins + +If you want to check if a specific plugin is registered you can use the `Reveal.hasPlugin` method and pass in a plugin ID, for example: `Reveal.hasPlugin( 'myPlugin' )`. If you want to retrieve a plugin instance you can use `Reveal.getPlugin( 'myPlugin' )`. + + ## Multiplexing 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/). The multiplex plugin needs the following 3 things to operate: @@ -1118,11 +1346,11 @@ url: 'https://reveal-js-multiplex-ccjbegmaii.now.sh' // Location of socket.io server }, // Don't forget to add the dependencies dependencies: [ - { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true }, + { src: '//cdnjs.cloudflare.com/ajax/libs/socket.io/2.2.0/socket.io.js', async: true }, { src: 'plugin/multiplex/master.js', async: true }, // and if you want speaker notes { src: 'plugin/notes-server/client.js', async: true } @@ -1131,11 +1359,11 @@ }); ``` #### Client presentation -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. +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 `https://example.com/path/to/presentation/client/index.html`, with the configuration below causing them to connect to the socket.io server as clients. Example configuration: ```javascript Reveal.initialize({ @@ -1148,11 +1376,11 @@ url: 'https://reveal-js-multiplex-ccjbegmaii.now.sh' // Location of socket.io server }, // Don't forget to add the dependencies dependencies: [ - { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true }, + { src: '//cdnjs.cloudflare.com/ajax/libs/socket.io/2.2.0/socket.io.js', async: true }, { src: 'plugin/multiplex/client.js', async: true } // other dependencies... ] }); @@ -1165,11 +1393,11 @@ 1. `npm install` 2. `node plugin/multiplex` Or you can use the socket.io server at [https://reveal-js-multiplex-ccjbegmaii.now.sh/](https://reveal-js-multiplex-ccjbegmaii.now.sh/). -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). +You'll need to generate a unique secret and token pair for your master and client presentations. To do so, visit `https://example.com/token`, where `https://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). 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. The easiest way to do this is by installing [now](https://zeit.co/now). With that installed, deploying your own Multiplex server is as easy running the following command from the reveal.js folder: `now plugin/multiplex`. @@ -1190,11 +1418,11 @@ url: 'example.com:80' // Location of your socket.io server }, // Don't forget to add the dependencies dependencies: [ - { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true }, + { src: '//cdnjs.cloudflare.com/ajax/libs/socket.io/2.2.0/socket.io.js', async: true }, { src: 'plugin/multiplex/client.js', async: true } // other dependencies... ] ``` @@ -1214,11 +1442,11 @@ url: 'example.com:80' // Location of your socket.io server }, // Don't forget to add the dependencies dependencies: [ - { src: '//cdn.socket.io/socket.io-1.3.5.js', async: true }, + { src: '//cdnjs.cloudflare.com/ajax/libs/socket.io/2.2.0/socket.io.js', async: true }, { src: 'plugin/multiplex/master.js', async: true }, { src: 'plugin/multiplex/client.js', async: true } // other dependencies... ] @@ -1228,82 +1456,40 @@ ## MathJax 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). -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. +The plugin defaults to using [LaTeX](https://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. 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. ```js Reveal.initialize({ // other options ... math: { mathjax: 'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js', - config: 'TeX-AMS_HTML-full' // See http://docs.mathjax.org/en/latest/config-files.html + config: 'TeX-AMS_HTML-full', // See http://docs.mathjax.org/en/latest/config-files.html + // pass other options into `MathJax.Hub.Config()` + TeX: { Macros: { RR: "{\\bf R}" } } }, dependencies: [ { src: 'plugin/math/math.js', async: true } ] }); ``` 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. +#### MathJax in Markdown +If you want to include math inside of a presentation written in Markdown you need to wrap the formula in backticks. This prevents syntax conflicts between LaTeX and Markdown. For example: -## Installation +``` +`$$ J(\theta_0,\theta_1) = \sum_{i=0} $$` +``` -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. - -### Basic setup - -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. - -1. Download the latest version of reveal.js from <https://github.com/hakimel/reveal.js/releases> -2. Unzip and replace the example contents in index.html with your own -3. Open index.html in a browser to view it - -### Full setup - -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. - -1. Install [Node.js](http://nodejs.org/) (4.0.0 or later) - -1. Clone the reveal.js repository - ```sh - $ git clone https://github.com/hakimel/reveal.js.git - ``` - -1. Navigate to the reveal.js folder - ```sh - $ cd reveal.js - ``` - -1. Install dependencies - ```sh - $ npm install - ``` - -1. Serve the presentation and monitor source files for changes - ```sh - $ npm start - ``` - -1. Open <http://localhost:8000> to view your presentation - - You can change the port by using `npm start -- --port=8001`. - -### Folder Structure - -- **css/** Core styles without which the project does not function -- **js/** Like above but for JavaScript -- **plugin/** Components that have been developed as extensions to reveal.js -- **lib/** All other third party assets (JavaScript, CSS, fonts) - - ## License MIT licensed -Copyright (C) 2018 Hakim El Hattab, http://hakim.se +Copyright (C) 2020 Hakim El Hattab, http://hakim.se