asciidoctor-revealjs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f17adb228c81df3f330ecd97c9d714daaf373dd7
+  data.tar.gz: e9093a912c533f637661ad9eadc8d6661e923199
+SHA512:
+  metadata.gz: 7e35b9133b7406edf2d4a0a5e9aec0c38b6672036a06ce32fae84f348c73e1b124ee137f3097328f9005965fa1ab90f0eca97e3d56abeba232154fc5d921a56e
+  data.tar.gz: 58b3fa54575ea6af8dd1d5fb27fe7086c6bf9de65a6a7779154fd12b6ea1ddac120d27a9c37d9cd683e4ffb77cb3494eeeabf03e9976f6a9d1f3a0389fc7d1ad

data/CHANGELOG.adoc

@@ -0,0 +1,46 @@
+= {project-name} Changelog
+:project-name: asciidoctor-reveal.js
+:uri-repo: https://github.com/asciidoctor/asciidoctor-reveal.js
+
+This document provides a high-level view of the changes introduced in {project-name} by release.
+For a detailed view of what has changed, refer to the {uri-repo}/commits/master[commit history] on GitHub.
+
+== 1.0.0 (2016-09-06) - @obilodeau
+
+Since this is the first ever "release" of asciidoctor-reveal.js (we used to do continuous improvements w/o releases in the past), this list focuses on the major enhancements introduced over the last few weeks.
+
+Enhancements::
+  * Initial release
+  * Ruby package (#93)
+  * Node package (#95)
+  * `:customcss:` attribute for easy per-presentation CSS (#85)
+  * Video support improvements (#81)
+  * Reveal.js `data-state` support (#61)
+  * Subtitle partioning (#70)
+  * Background image rework (#52)
+  * `:imagesdir:` properly enforced (#17, #67)
+
+////
+Compliance::
+  * item
+
+Bug fixes::
+  * item
+
+Infrastructure::
+  * item
+////
+
+=== Release meta
+
+Released by @obilodeau
+
+{uri-repo}/issues?q=milestone%3A1.0[issues resolved] |
+{uri-repo}/releases/tag/1.0[git tag]
+// TODO full-diff when we can at the next release
+
+=== Credits
+
+Thanks to the following people who contributed to this release:
+
+Alexander Heusingfeld, Andrea Bedini, Antoine Sabot-Durand, Brian Street, Charles Moulliard, Dan Allen, Danny Hyun, Emmanuel Bernard, gtoast, Guillaume Grossetie, Jacob Aae Mikkelsen, Jakub Jirutka, Jozef Skrabo, Julien Grenier, Julien Kirch, kubamarchwicki, lifei, Nico Rikken, nipa, Olivier Bilodeau, Patrick van Dissel, phrix32, Rahman Usta, Robert Panzer, Rob Winch, Thomas and Wendell Smith

data/HACKING.adoc

@@ -0,0 +1,250 @@
+= HACKING asciidoctor-reveal.js
+:toc: preamble
+:toclevels: 2
+
+Short instructions that aim to help potential contributors.
+
+== Inspect the template system
+
+
+To understand what you have access to in templates you can inject some ruby.
+With the slim templating system, this is done by prepending the lines with a dash (`-`) and inserting a ruby statement.
+Two complementary approaches can be used to explore the context offered by asciidoctor through the template system:
+
+* logging on the command line via print-like statements
+* jump into the context through an interactive debugger
+
+=== Print debugging information
+
+For example to see which attributes are available, you can print them by adding these lines in the `.slim` file of interest:
+
+----
+- puts @document.attributes.inspect
+- puts @attributes.inspect
+- puts @document.methods
+----
+
+Other generally useful ruby specific introspection:
+
+----
+- puts instance_variables
+- puts local_variables
+----
+
+One might find `pp` to produce better output (and in some cases not):
+
+----
+- require 'pp'
+- pp @document.attributes
+----
+
+=== Interactively debug a template
+
+Pry is a powerful debugger for ruby that features tab-completion.
+It is very useful to discover a complex object hierarchy like what asciidoctor offers.
+
+==== Initial Setup
+
+    gem install pry
+
+==== Usage
+
+In order to be dropped into the debugger at a specific point in a template simply add the following two lines in the relevant `.slim` template file:
+
+----
+- require 'pry'
+- binding.pry
+----
+
+Then run asciidoctor from the command-line to generate your document and you'll be dropped in the debugger:
+
+----
+$ make
+asciidoctor -T templates/slim -b revealjs test/level-sections.adoc
+asciidoctor: WARNING: level-sections.adoc: line 29: section title out of sequence: expected level 2, got level 3
+
+From: /home/olivier/src/asciidoc/asciidoctor-reveal.js/templates/slim/section.html.slim @ line 3 :
+
+    1: - hide_title = (title = self.title) == '!'
+    2: - require 'pry'
+ => 3: - binding.pry
+    4: / parent section of vertical slides set
+    5: - if @level == 1 && !(subsections = sections).empty?
+    6:   section
+    7:     section id=(hide_title ? nil : @id) data-transition=(attr 'data-transition') data-transition-speed=(attr 'data-transition-speed') data-background=(attr 'data-background') data-background-size=(attr 'data-background-size') data-background-repeat=(attr 'data-background-repeat') data-background-transition=(attr 'data-background-transition')
+    8:       - unless hide_title
+
+[1] pry(#<Asciidoctor::Section>)>
+----
+
+Then using commands like the following allows you to explore interactively asciidoctor's API and object model with syntax highlighting:
+
+    [1] pry(#<Asciidoctor::Section>)> @document
+
+You can also query asciidoctor's documentation:
+
+    [4] pry(#<Asciidoctor::Section>)> ? find_by
+
+=== References
+
+* https://github.com/asciidoctor/asciidoctor.org/issues/80#issuecomment-145698579
+* http://pryrepl.org/
+* http://discuss.asciidoctor.org/Interactively-debugging-a-template-with-a-REPL-td4498.html
+
+== Tests
+
+In order to help troubleshoot issues and test syntax improvements, some minimalist asciidoc test files are provided.
+You can render the tests files and then load them in a browser and check if `asciidoctor-reveal.js` behaves as expected.
+
+=== Initial Setup
+
+    cd test/
+    git clone https://github.com/hakimel/reveal.js.git
+
+=== Render tests into .html
+
+From the project's root directory:
+
+    make
+
+=== Open rendered files
+
+You can open the generated `.html` in a Web browser.
+For convenience the following command will open the last modified file:
+
+    make open
+
+Additionally, if you want to test with a minimalist web server:
+
+    make serve
+
+The server is running in the foreground and needs `Ctrl-C` to be killed.
+
+== Jade templates
+
+Jade templates are used by AsciidocFX. Since they are separate they might be
+out of sync with our asciidoctor's slim templates.
+
+To test the jade templates, install AsciidocFX and copy the jade templates
+over to AsciidocFX's `conf/slide/templates/revealjs/` directory. Then use
+AsciidocFX to render the slides.
+
+
+== Attribute inheritence
+
+The attr and attr? methods inherit by default. That means if they don't find the attribute defined on the node, they look on the document.
+
+You only want to enable inheritance if you intend to allow an attribute of the same name to be controlled globally.
+That might be good for configuring transitions. For instance:
+
+----
+= My Slides
+:transition-speed: fast
+
+== First Slide
+----
+
+However, there may be attributes that you don't want to inherit.
+If that's the case, you generally use the form:
+
+    attr('name', nil, false)
+
+The second parameter value is the default attribute value, which is nil by default.
+
+Relevant documentation: http://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FAbstractNode%3Aattr
+
+
+== Merge / Review policy
+
+Any non-trivial change should be integrated in master via a pull-request.
+This gives the community a chance to participate and helps write better code because it encourages people to review their own patches.
+
+Pull requests should come from personal forks in order not the clutter the upstream repository.
+
+=== Wait time
+
+Once a pull request is submitted, let it sit for 24-48 hours for small changes.
+If you get positive feedback you can merge before the sitting time frame.
+If you don't get feedback, just merge after the sitting time frame.
+
+Larger changes should sit longer at around a week.
+Positive feedback or no feedback should be handled like for small changes.
+
+Breaking changes should sit until a prominent contributor comments on the changes.
+Ping `@mojavelinux` and `@obilodeau` if necessary.
+
+Remember that this is a slower moving project since people are not designing slides everyday.
+Well, for most people.
+
+=== Work-in-progress pull-requests
+
+If you prepend "WIP" in front of your pull request we will understand that it is not complete and we will not merge it before you remove the WIP string.
+
+This is useful to let people know that you are working on stuff.
+Branches are not that visible otherwise but pull requests are.
+
+You might even be able to get some feedback early which could save you some time.
+
+=== 'needs review' label
+
+You can apply that label to a pull request that is complete and ready for review.
+
+Makes triaging easier.
+
+
+== Node package
+
+=== Test a local asciidoctor-reveal.js version
+
+In order to test the Node package, you need to create a test project adjacent to the clone of the `asciidoctor-reveal.js` repository:
+
+ $ mkdir test-project
+ $ cd test-project
+ $ npm init -y
+
+Now, install the dependencies:
+
+ $ npm i --save asciidoctor.js@1.5.5-2
+ $ npm i --save asciidoctor-template.js@1.5.5-2
+ $ npm i --save ../asciidoctor-reveal.js
+
+NOTE: The relative portion of the last command is where you are installing the local `asciidoctor-reveal.js` version from.
+
+Then proceed as documented in the `README.adoc`.
+
+
+=== Publish a new version
+
+. Update the "version" field in `package.json`
+. Commit and push your changes
+. Create a tag
+. Using npm:
++
+ $ npm login
+ $ npm publish
+
+. Check that the new version is available on https://www.npmjs.com/package/asciidoctor-reveal.js[npmjs.com]
+
+
+== Ruby gem
+
+=== Publish a new version
+
+. Update the version in `lib/asciidoctor-revealjs/version.rb`
+. Update the changelog
+** Generate author list with `git log <commit>.. --format="%aN" --reverse | perl -e 'my %dedupe; while (<STDIN>) { print unless $dedupe{$_}++}' | sort `
+. Prepare release commit
+** commit msg: Prepare %version% release
+** release commit (--allow-empty) msg: Release %version%
+. Tag the release commit
+** Annotated Tag msg: Version %version%
+. Push your changes (including the tag)
+. Pushing the gem on rubygems.org:
++
+ $ gem build asciidoctor-revealjs.gemspec
+ $ gem push asciidoctor-revealjs-X.Y.Z.gem
+
+. Check that the new version is available on https://rubygems.org/gems/asciidoctor-revealjs[rubygems.org]
+. Update version (+1 bugfix and append '.dev') and commit
+** commit msg: Begin development on next release
+

data/LICENSE.adoc

@@ -0,0 +1,22 @@
+.The MIT License
+....
+Copyright (C) 2012-2016 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+....

data/README.adoc

@@ -0,0 +1,671 @@
+= reveal.js backend for Asciidoctor
+:toc: preamble
+:toclevels: 2
+:uri-us: https://github.com/asciidoctor/asciidoctor-reveal.js
+:uri-asciidoctor: https://github.com/asciidoctor/asciidoctor
+:uri-asciidoctorjs: https://github.com/asciidoctor/asciidoctor.js
+:uri-revealjs-home: http://lab.hakim.se/reveal-js/
+:uri-revealjs-gh: https://github.com/hakimel/reveal.js
+:uri-nodejs-download: https://nodejs.org/en/download/
+
+// Changes made here should be sync'ed in packages.json's readme field
+The {uri-us}[reveal.js backend] is a collection of templates for {uri-asciidoctor}[Asciidoctor] (or {uri-asciidoctorjs}[Asciidoctor.js]) that transform an AsciiDoc document into HTML5 slides animated by {uri-revealjs-home}[reveal.js].
+
+//image:https://travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=https://travis-ci.org/asciidoctor/asciidoctor-reveal.js]
+
+There are two main technology stacks that can transform AsciiDoc into HTML5 / Reveal.js:
+
+* Asciidoctor / Ruby / Slim / Bundler (<<ruby, instructions here>>)
+* Asciidoctor.js / JavaScript / Jade / Node.js (<<javascript, instructions here>>)
+
+Right now the Ruby / Slim templates are more featureful but that is changing quickly.
+
+
+[[ruby]]
+== Ruby Setup
+
+NOTE: asciidoctor-reveal.js is now a Ruby Gem.
+To ensure repeatability, we recommend that you manage your presentation projects using bundler.
+
+For a quick start clone our https://github.com/obilodeau/presentation-revealjs-starter[starter repository] and follow instructions there.
+
+For more complete instructions, read on.
+
+NOTE: If you want to use reveal.js 2, please clone the asciidoctor-reveal.js repo and switch to the reveal.js-2.x branch.
+
+
+=== Prerequisites
+
+. Install http://bundler.io/[bundler] (if not already installed)  using your system's package manager or with:
+
+  $ gem install bundler
+
+. If you're using RVM, make sure you switch away from any gemset:
+
+  $ rvm use default
++
+or
++
+  $ rvm use system
+
+
+=== Install
+
+NOTE: These instructions should be repeated for every presentation project.
+
+. Create project directory
+
+  $ mkdir my-awesome-presentation
+  $ cd my-awesome-presentation
+
+. Create a file named `Gemfile` with the following content:
++
+----
+source 'https://rubygems.org'
+
+gem 'asciidoctor-revealjs', github: 'asciidoctor/asciidoctor-reveal.js'
+----
++
+NOTE: For some reason, when you use the system Ruby on Fedora, you also have to add the json gem to the Gemfile.
++
+. Install the gems into the project
+
+  $ bundle config --local github.https true
+  $ 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.3.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 or look at files in `test/`.
+
+. Generate HTML presentation from the AsciiDoc source
+
+  $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc
+
+TIP: If you are using https://pages.github.com/[GitHub Pages], plan ahead by keeping your source files on `master` branch and all output files on the `gh-pages` branch.
+
+
+[[javascript]]
+== Node / JavaScript Setup
+
+=== Prerequisites
+
+First you must install and configure {uri-nodejs-download}[Node.js] on your machine.
+
+=== Install
+
+Using npm:
+
+ $ npm i --save asciidoctor.js@1.5.5-2
+ $ npm i --save asciidoctor-template.js@1.5.5-2
+ $ npm i --save asciidoctor-reveal.js@1.5.5-2
+
+=== Rendering the AsciiDoc into slides
+
+Once the package is installed, you can convert AsciiDoc files using Reveal.js backend.
+Here we are converting a file named `presentation.adoc` into a Reveal.js presentation using Node.js:
+
+.asciidoctor-revealjs.js
+[source, javascript]
+----
+// Load asciidoctor.js + asciidoctor-template.js
+var asciidoctor = require('asciidoctor.js')();
+var Asciidoctor = asciidoctor.Asciidoctor();
+var Opal = asciidoctor.Opal;
+Opal.load('nodejs');
+Opal.load('pathname');
+require('asciidoctor-template.js');
+
+// Convert the document 'presentation.adoc' using Reveal.js backend
+var attributes = 'revealjsdir=node_modules/reveal.js@';
+var options = Opal.hash({safe: 'safe',
+                         backend: 'revealjs',
+                         attributes: attributes});
+Asciidoctor.$convert_file('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
+* World
+
+----
+
+To render the slides, run:
+
+    node asciidoctor-reveal.js
+
+You can open the `presentation.html` file in your browser and enjoy!
+
+
+== Syntax Examples
+
+// FIXME: incomplete
+
+Let's see some examples of `revealjs` backend features.
+
+=== Basic presentation with speaker notes
+
+----
+= Title Slide
+
+== Slide One
+
+* Foo
+* Bar
+* World
+
+== Slide Two
+
+Hello World - Good Bye Cruel World
+
+[NOTE.speaker]
+--
+Actually things aren't that bad
+--
+----
+
+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].
+
+
+=== Slides without titles
+
+There are a few ways to have no titles on slides.
+
+* Setting your title to `!`
+* Adding the `notitle` option to your slide
+* Adding the `conceal` option to your slide
+
+Here is an example of the three techniques in action:
+
+----
+include::test/concealed-slide-titles.adoc[]
+----
+
+NOTE: `conceal` and `notitle` have the advantage that the slide still has an id so it can be linked to.
+
+
+=== Background colors
+
+----
+[background-color="yellow"]
+== Slide Three
+
+Is very yellow
+----
+
+Slide Three applies the attribute {uri-revealjs-gh}#slide-backgrounds[data-background-color] to the `reveal.js` <section> tag.
+Anything accepted by CSS color formats works.
+
+
+=== Background images
+
+----
+[%notitle]
+== Grand Announcement
+
+image::cover.jpg[background, size=cover]
+----
+
+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: The `canvas` keyword can be used instead of `background` for the same effect.
+
+----
+[%notitle]
+== The Great Goat
+
+image::https://upload.wikimedia.org/wikipedia/commons/b/b2/Hausziege_04.jpg[canvas,size=contain]
+----
+
+As you can see, you can use a URL to specify your image resource too.
+
+
+[#background_videos]
+=== Background videos
+
+A background video for a slide can be specified using the `background-video` element attribute.
+
+----
+[background-video="https://my.video/file.mp4",background-video-loop=true,background-video-muted=true]
+== Nice background!
+----
+
+For convenience `background-video-loop` and `background-video-muted` attributes are mapped to `loop` and `muted` options which can be specified with `options="loop,muted"`.
+
+For example:
+
+----
+[background-video="https://my.video/file.mp4",options="loop,muted"]
+== Nice background!
+----
+
+See {uri-revealjs-gh}#video-backgrounds[the relevant reveal.js documentation] for details.
+Note that the `data-` prefix is not required in asciidoc files.
+
+
+=== Background iframes
+
+The background can be replaced with anything a browser can render in an iframe using the `background-iframe` reveal.js feature.
+
+----
+[%notitle,background-iframe="https://www.youtube.com/embed/LaApqL4QjH8?rel=0&start=3&enablejsapi=1&autoplay=1&loop=1&controls=0&modestbranding=1"]
+== a youtube video
+----
+
+See {uri-revealjs-gh}#iframe-backgrounds[the relevant reveal.js documentation] for details.
+
+
+=== Slide Transitions
+
+----
+[transition=zoom, %notitle]
+== Zoom zoom
+
+This slide will override the presentation transition and zoom!
+
+[transition-speed=fast, %notitle]
+== Speed
+
+Choose from three transition speeds: default, fast or slow!
+----
+
+See {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] for details.
+
+
+=== Fragments
+
+----
+== Slide Four
+
+[%step]
+* this
+* is
+* revealed
+* gradually
+----
+
+Slide Four has bullets that are revealed one after the other.
+This is what `reveal.js` calls http://lab.hakim.se/reveal-js/#/fragments[fragments].
+Applying the step option or role on a list (`[%step]` or `[.step]`) will do the trick.
+Here is {uri-revealjs-gh}#fragments[the relevant reveal.js
+documentation] on the topic.
+Note that only `fade-in` is supported for lists at the moment.
+
+
+=== Stretch class attribute
+
+Reveal.js supports a special class that will give all available screen space to an HTML node.
+This class element is named `stretch`.
+
+__
+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.
+__
+
+To apply that class to block simply use asciidoctor's class assignment:
+
+    [.stretch]
+
+See {uri-revealjs-gh}#stretching-elements[reveal.js documentation on stretching elements].
+
+
+=== Videos
+
+In addition to <<background_videos,background videos>>, videos can be inserted directly into slides.
+The syntax is the standard http://asciidoctor.org/docs/user-manual/#video[asciidoc video block macro] syntax.
+
+----
+== Trains, we love trains!
+
+video::kZH9JtPBq7k[youtube, start=34, options=autoplay]
+----
+
+By default videos are given as much space as possible.
+To override that behavior use the `width` and `height` named attributes.
+
+
+=== Syntax highlighting
+
+[listing]
+....
+== Slide Five
+
+Uses highlighted code
+
+----
+print "Hello World"
+----
+....
+
+`revealjs` uses https://highlightjs.org/[highlight.js] to do its syntax highlighting by default.
+By default `[source]` blocks and blocks delimited by `----` will be highlighted.
+An explicit `[listing]` block will not be highlighted.
+`highlight.js` does language auto-detection but using the `language="..."` attribute will hint the highlighter.
+For example this will highlight this source code as Perl:
+
+[listing]
+....
+== Slide Five
+
+[source,perl]
+----
+print "$0: hello world\n"
+----
+....
+
+[NOTE]
+Currently `revealjs` uses a rather old version of https://highlightjs.org/[highlight.js] that does not handle callouts correctly.
+To fix this download a current version of https://highlightjs.org/[highlight.js] and copy it to `reveal.js/plugin/highlight/highlight.js`.
+
+Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as the highlighter.
+These handle callouts correctly.
+
+To use http://coderay.rubychan.de[Coderay]:
+
+----
+= Title slide
+:source-highlighter: coderay
+----
+
+To use http://pygments.org[Pygments]:
+
+----
+= Title slide
+:source-highlighter: pygments
+----
+
+=== Vertical slides
+
+[listing]
+....
+== Slide Six
+
+Top slide
+
+=== Slide Six.One
+
+This is a vertical subslide
+....
+
+Slide Six uses the vertical slide feature of `reveal.js`.
+Slide Six.One will be rendered vertically below Slide Six.
+Here is {uri-revealjs-gh}#markup[the relevant reveal.js
+documentation] on that topic.
+
+
+
+=== 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`.
+
+This back-end supports changing the color, image, video, iframe and
+transitions of the title slide.
+
+Read {uri-revealjs-gh}#slide-backgrounds[the relevant
+reveal.js documentation] to understand what attributes need to be set.
+Keep in mind that for title slides you must replace `data-` with
+`title-slide-`.
+
+Here is an example:
+
+----
+include::test/title-slide-image.adoc[]
+----
+
+The title slide is also added a `title` CSS class to help with template
+customization.
+
+=== Content meant for multiple back-ends
+
+Some content can be created with both slides and book in mind.
+
+To mark slides split points you can use preprocessor conditionals combined
+with back-end declaration.
+Breaking points are set using slides with no title `=== !` wrapped in a
+conditional: `ifdef::backend-revealjs[=== !]`.
+In the end, the whole document has to be compiled with the back-end option:
+`-b revealjs`
+
+For example:
+
+----
+== Main section
+
+=== Sub Section
+
+Small +
+Multiline +
+intro
+
+. very
+. long
+. list
+. of
+. items
+
+\ifdef::backend-revealjs[=== !]
+
+Some overview diagram
+
+\ifdef::backend-revealjs[=== !]
+
+Detailed view diagram
+----
+
+
+=== 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.
+
+For example, to do proper position-independent text placement of a title slide with a specific background you can use:
+
+----
+.reveal section.title h1 {
+    margin-top: 2.3em;
+}
+
+.reveal section.title small {
+    margin-top: 15.3em;
+    font-weight: bold;
+    color: white;
+}
+----
+
+If the `:customcss:` attribute value is empty then `asciidoctor-revealjs.css` is the CSS resource that the presentation is linked to.
+
+
+=== Slide state
+
+Reveal.js supports a {uri-revealjs-gh}#slide-states[data-state] tag that can be added on slides which gets rendered into `<section>` tags.
+In AsciiDoc the `data-state` can be applied to a slide by adding a state attribute to a section like this:
+
+----
+[state=topic]
+== Epic Topic
+----
+
+That state can be queried from Javascript or used in CSS to apply further customization to your slide deck.
+For example, by combining this feature with the <<_css_override, CSS override>> one, you can alter fonts for specific pages with this CSS:
+
+----
+@import 'https://fonts.googleapis.com/css?family=Baloo+Bhai';
+
+section[data-state="topic"] h2 {
+    font-family: 'Baloo Bhai', cursive;
+    font-size: 4em;
+}
+----
+
+
+// FIXME this is no longer accurate
+== About Jade Templates
+
+`/templates/jade` directory contains jade template files they are ported from `/templates/slim` templates. These templates were written to support reveal.js backend for Asciidoctor.js environment that is currently using in https://github.com/asciidocfx/AsciidocFX[AsciidocFX] editor. You can look at the https://github.com/asciidocfx/asciidoctor.js-reveal-demo[demo].
+
+== reveal.js Options
+
+There are some attributes that can be set at the top of the document which they are specific of +revealjs+ backend.
+
+NOTE: Default settings are based on `reveal.js` default settings.
+
+[cols="1m,1,2"]
+|===
+|Attribute |Value(s) |Description
+
+|:revealjs_theme:
+|beige, *black*, league, night, serif, simple, sky, solarized, white
+|Chooses one of reveal.js' {uri-revealjs-gh}#theming[built-in themes].
+
+|:revealjs_customtheme:
+|<file\|URL>
+|Overrides CSS with given file or URL.
+Default is disabled.
+
+|:highlightjs-theme:
+|<file\|URL>
+|Overrides https://highlightjs.org[highlight.js] CSS style with given file or URL.
+Default is built-in [path]_lib/css/zenburn.css_.
+
+|:revealjsdir:
+|<file\|URL>
+|Overrides reveal.js directory.
+Example: ../reveal.js or
+https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.3.0
+
+|:revealjs_controls:
+|*true*, false
+|Display controls in the bottom right corner.
+
+|:revealjs_progress:
+|*true*, false
+|Display a presentation progress bar.
+
+|:revealjs_slideNumber:
+|true, *false*
+|Display the page number of the current slide.
+
+|:revealjs_history:
+|true, *false*
+|Push each slide change to the browser history.
+
+|:revealjs_keyboard:
+|*true*, false
+|Enable keyboard shortcuts for navigation.
+
+|:revealjs_overview:
+|*true*, false
+|Enable the slide overview mode.
+
+|:revealjs_touch:
+|*true*, false
+|Enables touch navigation on devices with touch input.
+
+|:revealjs_center:
+|*true*, false
+|Vertical centering of slides.
+
+|:revealjs_loop:
+|true, *false*
+|Loop the presentation.
+
+|:revealjs_rtl:
+|true, *false*
+|Change the presentation direction to be RTL.
+
+|:revealjs_fragments:
+|*true*, false
+|Turns fragments on and off globally.
+
+|: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_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_mouseWheel:
+|true, *false*
+|Enable slide navigation via mouse wheel.
+
+|:revealjs_hideAddressBar:
+|*true*, false
+|Hides the address bar on mobile devices.
+
+|:revealjs_previewLinks:
+|true, *false*
+|Opens links in an iframe preview overlay.
+
+|:revealjs_transition:
+|none, fade, *slide*, convex, concave, zoom
+|Transition style.
+
+|:revealjs_transitionSpeed:
+|*default*, fast, slow
+|Transition speed.
+
+|:revealjs_backgroundTransition:
+|none, *fade*, slide, convex, concave, zoom
+|Transition style for full page slide backgrounds.
+
+|:revealjs_viewDistance:
+|<integer>
+|Number of slides away from the current that are visible. Default: 3
+
+|:revealjs_parallaxBackgroundImage:
+|<file\|URL>
+|Parallax background image.
+Defaults to none
+
+|:revealjs_parallaxBackgroundSize:
+|<CSS size syntax>
+|Parallax background size (accepts any CSS syntax).
+Defaults to none
+|===
+
+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.
+
+== Minimum Requirements
+
+* asciidoctor 1.5.4
+
+== Copyright and Licensing
+
+Copyright (C) 2012-2016 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project.
+Free use of this software is granted under the terms of the MIT License.
+
+See the <<LICENSE#,LICENSE>> file for details.