README.adoc in asciidoctor-revealjs-1.0.4 vs README.adoc in asciidoctor-revealjs-1.1.0

- old
+ new

@@ -3,10 +3,11 @@ ifdef::env-github,env-browser[] :toc: preamble :toclevels: 2 endif::[] ifdef::env-github[] +:branch: master :status: :outfilesuffix: .adoc :!toc-title: :caution-caption: :fire: :important-caption: :exclamation: @@ -20,39 +21,45 @@ :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/ ifdef::env-github[] +image:https://travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=https://travis-ci.org/asciidoctor/asciidoctor-reveal.js] image:http://img.shields.io/gem/v/asciidoctor-revealjs.svg[gem, link=https://rubygems.org/gems/asciidoctor-revealjs] image:http://img.shields.io/npm/v/asciidoctor-reveal.js.svg[npm, link=https://www.npmjs.org/package/asciidoctor-reveal.js] endif::[] // IMPORTANT: Changes made to this description should be sync'ed with the readme field in package.json. {uri-project-repo}[Asciidoctor reveal.js] is a converter for {uri-asciidoctor}[Asciidoctor] and {uri-asciidoctorjs}[Asciidoctor.js] that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the {uri-revealjs-home}[reveal.js] presentation framework. -//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 (See <<Ruby Setup>>) -* Asciidoctor.js / JavaScript / Jade / Node.js (See <<Node / JavaScript Setup>>) +* Asciidoctor / Ruby / Bundler (See <<Ruby Setup>>) +* Asciidoctor.js / JavaScript (Node.js) / NPM (See <<Node / JavaScript Setup>>) -Right now the Ruby / Slim templates are more featureful but that is changing quickly. +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: + +{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::[] + == 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 @@ -80,11 +87,10 @@ [source,ruby] ---- source 'https://rubygems.org' gem 'asciidoctor-revealjs' # latest released version -#gem 'asciidoctor-revealjs', github: 'asciidoctor/asciidoctor-reveal.js' # github master branch ---- + 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 @@ -93,17 +99,17 @@ $ 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 + $ git clone -b 3.6.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/`. + See examples in <<Syntax Examples>> section to get started. . Generate HTML presentation from the AsciiDoc source $ bundle exec asciidoctor-revealjs CONTENT_FILE.adoc @@ -118,11 +124,10 @@ === Install Using npm: - $ npm i --save asciidoctor.js@1.5.5-5 $ 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. @@ -131,18 +136,16 @@ .asciidoctor-revealjs.js [source, javascript] ---- // Load asciidoctor.js and asciidoctor-reveal.js var asciidoctor = require('asciidoctor.js')(); -var Asciidoctor = asciidoctor.Asciidoctor(); - require('asciidoctor-reveal.js'); // Convert the document 'presentation.adoc' using the reveal.js converter -var attributes = 'revealjsdir=node_modules/reveal.js@'; +var attributes = {'revealjsdir': 'node_modules/reveal.js@'}; var options = {safe: 'safe', backend: 'revealjs', attributes: attributes}; -Asciidoctor.convertFile('presentation.adoc', options); // <1> +asciidoctor.convertFile('presentation.adoc', options); // <1> ---- <1> Creates a file named `presentation.html` (in the directory where command is run) .presentation.adoc [source, asciidoc] @@ -160,23 +163,23 @@ ---- To render the slides, run: - node asciidoctor-reveal.js + node asciidoctor-revealjs.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. +Additional examples can be found in the AsciiDoc files (.adoc) in `examples/`. === Basic presentation with speaker notes +[source, asciidoc] ---- = Title Slide == Slide One @@ -194,30 +197,44 @@ -- ---- 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]. +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`. +With Reveal.js 3.5 they require a webserver to work. +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/ + + === 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: +[source, asciidoc] ---- 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 +[source, asciidoc] ---- [background-color="yellow"] == Slide Three Is very yellow @@ -227,10 +244,11 @@ Anything accepted by CSS color formats works. === Background images +[source, asciidoc] ---- [%notitle] == Grand Announcement image::cover.jpg[background, size=cover] @@ -243,10 +261,11 @@ 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. +[source, asciidoc] ---- [%notitle] == The Great Goat image::https://upload.wikimedia.org/wikipedia/commons/b/b2/Hausziege_04.jpg[canvas,size=contain] @@ -258,19 +277,21 @@ [#background_videos] === Background videos A background video for a slide can be specified using the `background-video` element attribute. +[source, asciidoc] ---- [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: +[source, asciidoc] ---- [background-video="https://my.video/file.mp4",options="loop,muted"] == Nice background! ---- @@ -280,20 +301,22 @@ === Background iframes The background can be replaced with anything a browser can render in an iframe using the `background-iframe` reveal.js feature. +[source, asciidoc] ---- [%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 +[source, asciidoc] ---- [transition=zoom, %notitle] == Zoom zoom This slide will override the presentation transition and zoom! @@ -307,10 +330,11 @@ See {uri-revealjs-gh}#slide-transitions[the relevant reveal.js documentation] for details. === Fragments +[source, asciidoc] ---- == Slide Four [%step] * this @@ -344,10 +368,11 @@ === 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. +[source, asciidoc] ---- == Trains, we love trains! video::kZH9JtPBq7k[youtube, start=34, options=autoplay] ---- @@ -356,16 +381,17 @@ To override that behavior use the `width` and `height` named attributes. === Syntax highlighting -[listing] +[source, asciidoc] .... == Slide Five Uses highlighted code +[source, python] ---- print "Hello World" ---- .... @@ -373,11 +399,11 @@ 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] +[source, asciidoc] .... == Slide Five [source,perl] ---- @@ -392,25 +418,27 @@ 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]: +[source, asciidoc] ---- = Title slide :source-highlighter: coderay ---- To use http://pygments.org[Pygments]: +[source, asciidoc] ---- = Title slide :source-highlighter: pygments ---- === Vertical slides -[listing] +[source, asciidoc] .... == Slide Six Top slide @@ -440,10 +468,11 @@ Keep in mind that for title slides you must replace `data-` with `title-slide-`. Here is an example: +[source, asciidoc] ---- include::test/title-slide-image.adoc[] ---- The title slide is also added a `title` CSS class to help with template @@ -460,10 +489,11 @@ In the end, the whole document has to be compiled with the backend option: `-b revealjs` For example: +[source, asciidoc] ---- == Main section === Sub Section @@ -492,10 +522,11 @@ 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: +[source, css] ---- .reveal section.title h1 { margin-top: 2.3em; } @@ -512,18 +543,20 @@ === 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: +[source, asciidoc] ---- [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>> one, you can alter fonts for specific pages with this CSS: +[source, css] ---- @import 'https://fonts.googleapis.com/css?family=Baloo+Bhai'; section[data-state="topic"] h2 { font-family: 'Baloo Bhai', cursive; @@ -534,30 +567,27 @@ === Admonitions Asciidoctor font-based http://asciidoctor.org/docs/user-manual/#admonition[admonitions] are supported. Make sure to add the following attribute to your document: +[source, asciidoc] ---- :icons: font ---- Here is an example slide: +[source, asciidoc] ---- == But first WARNING: This presentation is dangerous! ---- Here are details about Asciidoctor's http://asciidoctor.org/docs/user-manual/#admonition-icons[Admonition icons] support. -// 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 the reveal.js converter 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` converter. NOTE: Default settings are based on `reveal.js` default settings. @@ -689,13 +719,13 @@ theme documentation] and use the `revealjs_customtheme` AsciiDoc attribute to activate it. == Minimum Requirements -* asciidoctor 1.5.4 +* asciidoctor 1.5.6 == Copyright and Licensing -Copyright (C) 2012-2016 {authors} and the Asciidoctor Project. +Copyright (C) 2012-2017 {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.]