README.adoc in asciidoctor-revealjs-1.1.3 vs README.adoc in asciidoctor-revealjs-2.0.0

- old
+ new

@@ -38,12 +38,14 @@ * Asciidoctor.js / JavaScript (Node.js) / NPM (See <<Node / JavaScript Setup>>) Right now the Asciidoctor / Ruby stack is the better tested one but with the changes in v1.1.0 they have feature parity. ifeval::['{branch}' == 'master'] -NOTE: You're viewing the documentation for the upcoming release. -If you're looking for the documentation for an older release, please refer to one of the following branches: + +NOTE: You're viewing the documentation for an upcoming release. +If you're looking for the documentation for the current release or an older one, please click on the appropriate link below: + +{uri-project-repo}/tree/v1.1.3#readme[1.1.3] (latest release) +&hybull; {uri-project-repo}/tree/maint-1.0.x#readme[1.0.x] &hybull; {uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with RevealJS 2.x) endif::[] @@ -99,22 +101,22 @@ $ bundle --path=.bundle/gems --binstubs=.bundle/.bin . Optional: Copy or clone reveal.js presentation framework. Allows you to modify themes or view slides offline. - $ git clone -b 3.6.0 --depth 1 https://github.com/hakimel/reveal.js.git + $ git clone -b 3.7.0 --depth 1 https://github.com/hakimel/reveal.js.git === Rendering the AsciiDoc into slides . Create content in a file (*.adoc, *.ad, etc.). See examples in <<Syntax Examples>> section to get started. . Generate HTML presentation from the AsciiDoc source $ bundle exec asciidoctor-revealjs \ - -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.6.0 CONTENT_FILE.adoc + -a revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0 CONTENT_FILE.adoc . If you did the optional step of having a local reveal.js clone you can convert AsciiDoc source with $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc @@ -130,10 +132,13 @@ === Install Using npm: +Create a directory to place slides. Initialize the directory to store npm packages within that directory. + + $ echo {} > package.json # eliminates warnings, use `npm init` if you prefer $ npm i --save asciidoctor-reveal.js === Rendering the AsciiDoc into slides Once the package is installed, you can convert AsciiDoc files using reveal.js converter. @@ -142,26 +147,23 @@ .asciidoctor-revealjs.js [source, javascript] ---- // Load asciidoctor.js and asciidoctor-reveal.js var asciidoctor = require('asciidoctor.js')(); -require('asciidoctor-reveal.js'); +var asciidoctorRevealjs = require('asciidoctor-reveal.js'); +asciidoctorRevealjs.register() // Convert the document 'presentation.adoc' using the reveal.js converter -var attributes = {'revealjsdir': 'node_modules/reveal.js@'}; -var options = {safe: 'safe', backend: 'revealjs', attributes: attributes}; +var options = {safe: 'safe', backend: 'revealjs'}; asciidoctor.convertFile('presentation.adoc', options); // <1> ---- <1> Creates a file named `presentation.html` (in the directory where command is run) .presentation.adoc [source, asciidoc] ---- = Title Slide -// depending on your npm version, you might need to override the default -// 'revealjsdir' value by removing the comments from the line below: -//:revealjsdir: node_modules/asciidoctor-reveal.js/node_modules/reveal.js == Slide One * Foo * Bar @@ -193,19 +195,21 @@ * Bar * World == Slide Two -Hello World - Good Bye Cruel World +A Great Story -[NOTE.speaker] +[.notes] -- -Actually things aren't that bad +* tell anecdote +* make a point -- ---- In previous snippet we are creating a slide titled Slide One with bullets and another one titled Slide Two with centered text (reveal.js`' default behavior) with {uri-revealjs-gh}#speaker-notes[speaker notes]. +Other syntax exists to create speaker notes, see `examples/speaker-notes.adoc`. Starting with Reveal.js 3.5 speaker notes supports configurable layouts: image:https://cloud.githubusercontent.com/assets/629429/21808439/b941eb52-d743-11e6-9936-44ef80c60580.gif[] Speaker notes are opened by pressing `s`. @@ -213,13 +217,12 @@ This limitation is not present in 3.6. You can get a Web server running quickly with: ruby -run -e httpd . -p 5000 -b 127.0.0.1 -Then open your browser at: http://localhost:5000/ +Then use your browser to navigate to the URL \http://localhost:5000. - === Slides without titles There are a few ways to have no titles on slides. * Setting your title to `!` @@ -239,15 +242,53 @@ .... endif::[] NOTE: `conceal` and `notitle` have the advantage that the slide still has an id so it can be linked to. +IMPORTANT: Like the first page of an AsciiDoc document, the first slide is handled differently. + To hide the whole slide use the `:notitle:` http://asciidoctor.org/docs/user-manual/#header-summary[document attribute]. + To achieve the effect of hiding only the first slide's title, combine the `:notitle:` attribute on the first slide and use `[%notitle]` on the second slide which will, in effect, be your first slide now. -=== Background colors +=== Background Colors + +Background colors for slides can be specified by two means: a classic one and one using AsciiDoc roles. +See <<examples/background-color.adoc#,background-color.adoc>> for more examples. + +==== Using AsciiDoc Roles + +Using roles respects the AsciiDoc philosophy of separation of content and presentation. +Colors are to be defined by CSS and the <<customcss,`:customcss:` attribute>> need to be used to specify the CSS file to load. +To avoid clashing with existing reveal.js themes or CSS, a specific CSS class called `background` is expected to be present. +Here is an example: + + [source, asciidoc] ---- += Title +:customcss: my-css.css + +[.red.background] +== Slide One + +Is very red +---- + +.my-css.css +[source, css] +---- +section.red.background { + background-color: red; +} +---- + +NOTE: The `canvas` keyword can be used instead of `background` for the same effect. + +==== Classic + +[source, asciidoc] +---- [background-color="yellow"] == Slide Three Is very yellow ---- @@ -269,11 +310,11 @@ This will put `cover.jpg` as the slide's background image. It sets reveal.js`' `data-background-image` attribute. The `size` attribute is also supported. See the {uri-revealjs-gh}#image-backgrounds[relevant reveal.js documentation] for details. -NOTE: Background images file names are now relative to the `:imagedir:` attribute if set. +NOTE: Background images file names are now relative to the `:imagesdir:` attribute if set. NOTE: The `canvas` keyword can be used instead of `background` for the same effect. [source, asciidoc] ---- @@ -458,11 +499,45 @@ Slide Six.One will be rendered vertically below Slide Six. Here is {uri-revealjs-gh}#markup[the relevant reveal.js documentation] on that topic. +=== Asciidoctor-reveal.js specific roles +Roles are usually applied with the following syntax where the `important-text` CSS class would be applied to the slide title in the generated HTML: + +[source, asciidoc] +.... +[.important-text] +== Slide Title + +* Some +* Information +.... + +Or + +[source, asciidoc] +.... +[role="important-text"] +== Slide Title + +* Some +* Information +.... + +See https://asciidoctor.org/docs/user-manual/#role[Asciidoctor's documentation] for more details. + +.Image specific note +In addition to the https://asciidoctor.org/docs/user-manual/\#positioning-attributes[existing attributes] to position images, roles can be used as well. However, the shorthand syntax (.) doesn't work in the image macro arguments but must be used above with the angle bracket syntax. +See <<examples/images.adoc#,images.adoc>> for examples. + +Here is a list of supported roles: + +right:: Will apply a `float: right` style to the affected block + + === Title slide customization The title slide is customized via Asciidoc attributes. These are the global variable assigned at the top of a document under the lead title that look like this: `:name: value`. @@ -525,10 +600,11 @@ Detailed view diagram ---- +[[customcss]] === CSS override If you use the `:customcss:` document attribute, a CSS file of the name given in the attribute is added to the list of CSS resources loaded by the rendered HTML. Doing so, you can then easily override specific elements of your theme per presentation. @@ -622,24 +698,52 @@ |:revealjsdir: |<file\|URL> |Overrides reveal.js directory. Example: ../reveal.js or -https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.3.0 +https://cdnjs.com/libraries/reveal.js/3.7.0[https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0]. +Default is `reveal.js/` unless in a Node.js environment where it is `node_modules/reveal.js/`. |:revealjs_controls: |*true*, false -|Display controls in the bottom right corner. +|Display presentation control arrows +|:revealjs_controlsTutorial: +|*true*, false +|Help the user learn the controls by providing hints, for example by bouncing the down arrow when they first encounter a vertical slide + +|:revealjs_controlsLayout: +|edges, *bottom-right* +|Determines where controls appear, "edges" or "bottom-right" + +|:revealjs_controlsBackArrows: +|*faded*, hidden, visible +|Visibility rule for backwards navigation arrows; "faded", "hidden" or "visible" + |:revealjs_progress: |*true*, false |Display a presentation progress bar. |:revealjs_slideNumber: -|true, *false* -|Display the page number of the current slide. +|true, *false*, h.v, h/v, c, c/t +a|Display the page number of the current slide. +*true* will display the slide number with default formatting. +Additional formatting is available: +h.v:: horizontal . vertical slide number (default) +h/v:: horizontal / vertical slide number +c:: flattened slide number +c/t:: flattened slide number / total slides + +|:revealjs_showSlideNumber: +|*all*, speaker, print +a|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 + |:revealjs_history: |true, *false* |Push each slide change to the browser history. |:revealjs_keyboard: @@ -668,24 +772,54 @@ |:revealjs_fragments: |*true*, false |Turns fragments on and off globally. +|:revealjs_fragmentInURL: +|true, *false* +|Flags whether to include the current fragment in the URL, so that reloading brings you to the same fragment position + |:revealjs_embedded: |true, *false* |Flags if the presentation is running in an embedded mode (i.e., contained within a limited portion of the screen). +|:revealjs_help: +|*true*, false +|Flags if we should show a help overlay when the questionmark key is pressed + +|:revealjs_showNotes: +|*true*, false +|Flags if speaker notes should be visible to all viewers + +|:revealjs_autoPlayMedia: +|*null*, true, false +a|Global override for autolaying embedded media (video/audio/iframe) + +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 + |:revealjs_autoSlide: |<integer> |Delay in milliseconds between automatically proceeding to the next slide. Disabled when set to *0* (the default). This value can be overwritten by using a `data-autoslide` attribute on your slides. |:revealjs_autoSlideStoppable: |*true*, false |Stop auto-sliding after user input. +|:revealjs_autoSlideMethod: +|*Reveal.navigateNext* +|Use this method for navigation when auto-sliding + +|:revealjs_defaultTiming: +|<integer> +|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. +Defaults to *120* + |:revealjs_mouseWheel: |true, *false* |Enable slide navigation via mouse wheel. |:revealjs_hideAddressBar: @@ -693,10 +827,11 @@ |Hides the address bar on mobile devices. |:revealjs_previewLinks: |true, *false* |Opens links in an iframe preview overlay. +Add `data-preview-link` and `data-preview-link="false"` to customise each link individually |:revealjs_transition: |none, fade, *slide*, convex, concave, zoom |Transition style. @@ -719,23 +854,104 @@ |:revealjs_parallaxBackgroundSize: |<CSS size syntax> |Parallax background size (accepts any CSS syntax). Defaults to none + +|:revealjs_parallaxBackgroundHorizontal: +|<Number of pixels> +a|Number of pixels to move the parallax background per slide + +- Calculated automatically unless specified +- Set to 0 to disable movement along an axis + +|:revealjs_parallaxBackgroundVertical: +|<Number of pixels> +a|Number of pixels to move the parallax background per slide + +- Calculated automatically unless specified +- Set to 0 to disable movement along an axis + +|:revealjs_display: +|<a valid CSS display mode> +|The display mode that will be used to show slides. +Defaults to *block* |=== If you want to build a custom theme or customize an existing one you should look at the {uri-revealjs-gh}/blob/master/css/theme/README.md[reveal.js theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to activate it. +=== Default plugins + +By default, generated presentations will have the following reveal.js plugins enabled: + +* plugin/zoom-js/zoom.js +* plugin/notes/notes.js + +All these plugins are part of the reveal.js distribution. + +To enable or disable a built-in plugin, it is possible to set the `revealjs_plugin_[plugin name]` attribute to `enable` or `disable`. + +For example, to disable all the default plugins set the following document attributes: + +---- +:revealjs_plugin_zoom: disabled +:revealjs_plugin_notes: disabled +---- + +reveal.js ships with a plugin that allows to create a PDF from a slide deck. +To enable this plugin, set the `revealjs_plugin_pdf` attribute. + +---- +:revealjs_plugin_pdf: enabled +---- + +When the plugin is enabled and you run your presentation in a browser with `?print-pdf` at the end of the URL, you can then use the default print function to print the slide deck into a PDF document. + +TIP: To work properly, this plugin requires a Chrome-based browser. + + +=== Additional plugins + +Additional reveal.js plugins can be installed and activated using AsciiDoc attributes and external javascript files. + +. Extract the plugin files in a directory +. Create a Javascript file that will contain the Javascript statements to load the plugin (only one required even if you are using several plugins) +. Add a `:revealjs_plugins:` attribute to point to that Javascript file +. (Optional) Add a `:revealjs_plugins_configuration:` attribute to point to a Javascript file that configures the plugins you use + +Looking at the example provided in the repository will provide guidance: link:examples/revealjs-plugins.adoc[AsciiDoc source], link:examples/revealjs-plugins.js[Plugin Loader], link:examples/revealjs-plugins-conf.js[Plugin Configuration]. + +Read {uri-revealjs-gh}#dependencies[the relevant reveal.js documentation] to understand more about reveal.js plugins. +A {uri-revealjs-gh}/wiki/Plugins,-Tools-and-Hardware[list of existing reveal.js plugins] is also maintained upstream. + + == Minimum Requirements -* asciidoctor 1.5.6 +Our requirements are expressed in our packages and by our dependencies. +Basically, all you need is the package manager of the flavor of Asciidoctor-Reveal.js you are interested to run: +* With Ruby / Bundler: A https://www.ruby-lang.org/en/downloads/[recent Ruby] and https://bundler.io/[Bundler] +* With Javascript (Node.js) / NPM: a https://nodejs.org/en/download/[recent Node.js] environment + +If you need more details about our dependencies check out Asciidoctor dependencies: + +* With Ruby / Bundler: https://asciidoctor.org/#requirements[Asciidoctor] 1.5.6 +* With Javascript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v1.5.6/package.json[Asciidoctor.js] 1.5.6 + + +== Contributing + +Interested in contributing? +We are interested! +Developer-focused documentation is link:HACKING.adoc[over here]. + + == Copyright and Licensing -Copyright (C) 2012-2018 {authors} and the Asciidoctor Project. +Copyright (C) 2012-2019 {authors} and the Asciidoctor Project. Free use of this software is granted under the terms of the MIT License. ifdef::env-github,env-browser[See the <<LICENSE#,LICENSE>> file for details.]