README.adoc in asciidoctor-revealjs-1.0.1 vs README.adoc in asciidoctor-revealjs-1.0.2

- old
+ new

@@ -1,29 +1,46 @@ -= reveal.js backend for Asciidoctor += Reveal.js converter for Asciidoctor +Olivier Bilodeau <https://github.com/obilodeau[@obilodeau]>; Guillaume Grossetie <https://github.com/mogztter[@mogztter]>; Dan Allen <https://github.com/mojavelinux[@mojavelinux]>; Rahman Usta <https://github.com/rahmanusta[@rahmanusta]>; Charles Moulliard <https://github.com/cmoulliard[@cmoulliard]> +ifdef::env-github,env-browser[] :toc: preamble :toclevels: 2 -:uri-us: https://github.com/asciidoctor/asciidoctor-reveal.js +endif::[] +ifdef::env-github[] +:status: +:outfilesuffix: .adoc +:!toc-title: +:caution-caption: :fire: +:important-caption: :exclamation: +:note-caption: :paperclip: +:tip-caption: :bulb: +:warning-caption: :warning: +endif::[] +:uri-project-repo: 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]. +ifdef::env-github[] +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: +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>>) +* Asciidoctor / Ruby / Slim / Bundler (See <<Ruby Setup>>) +* Asciidoctor.js / JavaScript / Jade / Node.js (See <<Node / JavaScript Setup>>) 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. @@ -58,10 +75,11 @@ $ mkdir my-awesome-presentation $ cd my-awesome-presentation . Create a file named `Gemfile` with the following content: + +[source,ruby] ---- source 'https://rubygems.org' gem 'asciidoctor-revealjs' # latest released version #gem 'asciidoctor-revealjs', github: 'asciidoctor/asciidoctor-reveal.js' # github master branch @@ -90,47 +108,41 @@ $ 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 + $ npm i --save asciidoctor.js@1.5.5-3 + $ npm i --save asciidoctor-reveal.js === 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: +Once the package is installed, you can convert AsciiDoc files using reveal.js converter. +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 +// Load asciidoctor.js and asciidoctor-reveal.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 +require('asciidoctor-reveal.js'); + +// Convert the document 'presentation.adoc' using the reveal.js converter var attributes = 'revealjsdir=node_modules/reveal.js@'; -var options = Opal.hash({safe: 'safe', - backend: 'revealjs', - attributes: attributes}); -Asciidoctor.$convert_file('presentation.adoc', options); // <1> +var options = {safe: 'safe', backend: 'revealjs', attributes: attributes}; +Asciidoctor.convertFile('presentation.adoc', options); // <1> ---- <1> Creates a file named `presentation.html` (in the directory where command is run) .presentation.adoc [source, asciidoc] @@ -180,11 +192,11 @@ -- 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]. +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. @@ -223,11 +235,11 @@ 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. +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. @@ -318,24 +330,22 @@ === 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. +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! @@ -420,11 +430,11 @@ 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 +This converter 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 @@ -437,19 +447,19 @@ ---- The title slide is also added a `title` CSS class to help with template customization. -=== Content meant for multiple back-ends +=== Content meant for multiple converters 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. +with a backend 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: +In the end, the whole document has to be compiled with the backend option: `-b revealjs` For example: ---- @@ -508,11 +518,11 @@ [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: +For example, by combining this feature with the <<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 { @@ -523,25 +533,25 @@ // 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]. +`/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 +== Reveal.js Options -There are some attributes that can be set at the top of the document which they are specific of +revealjs+ backend. +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. [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]. +|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. @@ -664,9 +674,9 @@ * asciidoctor 1.5.4 == Copyright and Licensing -Copyright (C) 2012-2016 Olivier Bilodeau, Charles Moulliard, Dan Allen and the Asciidoctor Project. +Copyright (C) 2012-2016 {authors} 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. +ifdef::env-github,env-browser[See the <<LICENSE#,LICENSE>> file for details.]