README.adoc in asciidoctor-revealjs-2.0.1 vs README.adoc in asciidoctor-revealjs-3.0.0.pre.rc1

- old
+ new

@@ -19,32 +19,34 @@ :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/ +:showcasedir: showcase 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] +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. +TIP: Want to see some example presentations, see <<Showcase Presentations>> There are two main technology stacks that can transform AsciiDoc into HTML5 / reveal.js: * Asciidoctor / Ruby / Bundler (See <<Ruby Setup>>) -* Asciidoctor.js / JavaScript (Node.js) / NPM (See <<Node / JavaScript Setup>>) +* 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 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/v2.0.0#readme[2.0.0] (latest release) +{uri-project-repo}/tree/v2.0.1#readme[2.0.1] (latest release) &hybull; {uri-project-repo}/tree/v1.1.3#readme[1.1.3] (latest from 1.1 series) &hybull; {uri-project-repo}/tree/maint-1.0.x#readme[1.0.x] &hybull; @@ -128,42 +130,47 @@ == Node / JavaScript Setup === Prerequisites -First you must install and configure {uri-nodejs-download}[Node.js] on your machine. +First you must install and configure {uri-nodejs-download}[Node] on your machine. === Install -Using npm: +We recommend to install the dependencies in a project directory, such as the directory where your AsciiDoc presentations are stored. +If you don't have a `package.json` file in your project directory, you can create one to eliminate warnings during the installation using: -Create a directory to place slides. Initialize the directory to store npm packages within that directory. + $ npm init -y - $ echo {} > package.json # eliminates warnings, use `npm init` if you prefer - $ npm i --save asciidoctor-reveal.js +You can now install the dependencies: -=== Rendering the AsciiDoc into slides + $ npm i --save asciidoctor @asciidoctor/reveal.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: +=== Convert AsciiDoc into slides -.asciidoctor-revealjs.js -[source, javascript] ----- -// Load asciidoctor.js and asciidoctor-reveal.js -var asciidoctor = require('asciidoctor.js')(); -var asciidoctorRevealjs = require('asciidoctor-reveal.js'); -asciidoctorRevealjs.register() +Once the dependencies are installed, verify that the `asciidoctor` command is available. +On Linux and macOS, open a terminal and type: -// Convert the document 'presentation.adoc' using the reveal.js converter -var options = {safe: 'safe', backend: 'revealjs'}; -asciidoctor.convertFile('presentation.adoc', options); // <1> + $ $(npm bin)/asciidoctor --version + +On Windows, open PowerShell and type: + + $ .\node_modules\.bin\asciidoctor.cmd --version + +The command should report the Asciidoctor CLI version in the terminal: + +[source,console] ---- -<1> Creates a file named `presentation.html` (in the directory where command is run) +Asciidoctor.js 2.0.3 (Asciidoctor 2.0.9) [https://asciidoctor.org] +Runtime Environment (node v10.15.1 on linux) +CLI version 2.0.1 +---- +If you don't have an existing presentation, you can create a sample presentation named [.path]_presentation.adoc_: + .presentation.adoc -[source, asciidoc] +[source,asciidoc] ---- = Title Slide == Slide One @@ -171,17 +178,45 @@ * Bar * World ---- -To render the slides, run: +To convert the sample presentation into slides, open a terminal and type: - node asciidoctor-revealjs.js + $ $(npm bin)/asciidoctor -r @asciidoctor/reveal.js -b revealjs presentation.adoc -You can open the `presentation.html` file in your browser and enjoy! +On windows, open PowerShell and type: + $ .\node_modules\.bin\asciidoctor.cmd -r @asciidoctor/reveal.js -b revealjs presentation.adoc + +The above command will generate a file named [.path]_presentation.html_. +You can open this file in a browser. +==== Using the JavaScript API + +Alternatively, you can use the JavaScript API to register the converter and convert a document: + +.convert-slides.js +[source,javascript] +---- +// Load Asciidoctor.js and the reveal.js converter +var asciidoctor = require('@asciidoctor/core')() +var asciidoctorRevealjs = require('@asciidoctor/reveal.js') +asciidoctorRevealjs.register() + +// Convert the document 'presentation.adoc' using the reveal.js converter +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) + +To execute the script, open a terminal and type: + + $ node convert-slides.js + +You can open the `presentation.html` file in your browser and enjoy! + == Syntax Examples Let's see some examples of `revealjs` backend features. Additional examples can be found in the AsciiDoc files (.adoc) in `examples/`. @@ -477,11 +512,11 @@ print "$0: hello world\n" ---- .... [NOTE] -Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as syntax highlighters if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/Javascript/NPM). +Alternatively, you can use http://coderay.rubychan.de[Coderay] or http://pygments.org[Pygments] as syntax highlighters if you are using the Asciidoctor/Ruby/Bundler toolchain (not Asciidoctor.js/JavaScript/npm). Check the `examples/` directory for examples and notes about what needs to be done for them to work. They are considered unsupported by the asciidoctor-reveal.js project. === Vertical slides @@ -637,11 +672,11 @@ ---- [state=topic] == Epic Topic ---- -That state can be queried from Javascript or used in CSS to apply further customization to your slide deck. +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'; @@ -891,10 +926,20 @@ |:revealjs_margin: |<percentage value> | Factor of the display size that should remain empty around the content. Defaults to *0.1* +|:revealjs_pdfseparatefragments: +|*true*, false +|In PDF export, put each fragment on a separate page. +Defaults to *true* + +|:revealjs_pdfmaxpagesperslide: +|<integer> +|In PDF export, when a slide does not fit on a single page, maximum number of pages. +Defaults to *1* + |=== 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 @@ -934,31 +979,47 @@ === 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 +. 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 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: +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 +* 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 +* With Ruby / Bundler: https://github.com/asciidoctor/asciidoctor/tree/v2.0.10#requirements[Asciidoctor] 2.0.10 +* With JavaScript (Node.js) / NPM: https://github.com/asciidoctor/asciidoctor.js/blob/v2.0.3/packages/core/package.json[Asciidoctor.js] 2.0.3 + + +== Showcase Presentations + +=== Power Catchup -- Everything Practical and Important in Java 9 to 13 + +A smooth presentation, featuring video backgrounds, slide transitions, code and callout examples and the use of notes. + +https://bentolor.github.io/java9to13/[Presentation] and https://github.com/bentolor/java9to13[source] + +==== Screenshots + +image:{showcasedir}/java9to13_4.png[width=200,link=./{showcasedir}/java9to13_4.png] image:{showcasedir}/java9to13_1.jpg[width=200,link={showcasedir}/java9to13_1.jpg] + +image:{showcasedir}/java9to13_2.jpg[width=200,link={showcasedir}/java9to13_2.jpg] +image:{showcasedir}/java9to13_3.png[width=200,link={showcasedir}/java9to13_3.png] == Contributing Interested in contributing?