Reveal.js converter for Asciidoctor
¶ ↑
Olivier Bilodeau <github.com/obilodeau[@obilodeau]>; Guillaume Grossetie <github.com/mogztter[@mogztter]>; Dan Allen <github.com/mojavelinux[@mojavelinux]>; Rahman Usta <github.com/rahmanusta[@rahmanusta]>; Charles Moulliard <github.com/cmoulliard[@cmoulliard]> 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: :note-caption: :paperclip: :tip-caption: :bulb: :warning-caption: :warning: endif::[] :uri-project-repo: github.com/asciidoctor/asciidoctor-reveal.js :uri-asciidoctor: github.com/asciidoctor/asciidoctor :uri-asciidoctorjs: github.com/asciidoctor/asciidoctor.js :uri-revealjs-home: revealjs.com :uri-revealjs-gh: github.com/hakimel/reveal.js/blob/v3.9 :uri-revealjs-doc: {uri-revealjs-gh}/README.md :uri-nodejs-download: nodejs.org/en/download/ :showcasedir: showcase
ifdef::env-github[] image:travis-ci.org/asciidoctor/asciidoctor-reveal.js.svg?branch=master[Build Status,link=travis-ci.org/asciidoctor/asciidoctor-reveal.js] image:img.shields.io/gem/v/asciidoctor-revealjs.svg[gem, link=rubygems.org/gems/asciidoctor-revealjs] image:img.shields.io/npm/v/@asciidoctor/reveal.js.svg[npm, link=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 and uri-asciidoctorjs that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the uri-revealjs-home presentation framework.
TIP: Want to see some example presentations, see <<Showcase Presentations>>
There are four main technology stacks that can convert AsciiDoc into HTML5 / reveal.js:
-
Asciidoctor
/ Ruby / Bundler (See <<Ruby Setup>>) -
Asciidoctor.js / JavaScript (Node.js) / npm (See <<Node / JavaScript Setup>>)
-
Standalone Executable (See <<Standalone Executable>>)
-
AsciidoctorJ / JVM / Maven (See github.com/asciidoctor/asciidoctorj-reveal.js[this project])
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/v4.0.0#readme (latest from 4.x series) ⁃ {uri-project-repo}/tree/v3.1.0#readme (latest from 3.x series) ⁃ {uri-project-repo}/tree/reveal.js-2.x#readme[Unversioned pre-release] (compatible with reveal.js 2.x) endif::[]
Ruby Setup¶ ↑
NOTE: To ensure repeatability, we recommend that you manage your presentation projects using bundler.io/[bundler].
Prerequisites¶ ↑
. Install 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,ruby
source 'rubygems.org'
gem 'asciidoctor-revealjs' # latest released version
+ 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.9.2 --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://cdn.jsdelivr.net/npm/reveal.js@3.9.2 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
TIP: If you are using pages.github.com/[GitHub Pages], plan ahead by keeping your source files on `master` branch and all output files on the `gh-pages` branch.
Features Unique to the Ruby CLI¶ ↑
Starting with 4.0.0 you can specify a set of custom templates to use instead of the ones provided by this project. This can help you achieve even more concise AsciiDoc syntax and integration with reveal.js at the cost of more maintenance.
To use it, add the following dependencies to your `Gemfile`:
gem 'tilt', '~>2.0' gem 'slim', '~>4.0'
Then install the dependencies with:
$ bundle install
The feature is activated with the `–template-dir` or `-T` option:
$ bundle exec asciidoctor-revealjs -T templates/ CONTENT_FILE.adoc
Any individual template file not provided in the directory specified on the command-line will fall back to the template provided by your version of
Asciidoctor
reveal.js. Refer to our github.com/asciidoctor/asciidoctor-reveal.js/tree/master/templates[templates] for inspiration.This feature hasn't been ported to the JavaScript CLI (and API) or the standalone executables.
Node / JavaScript Setup¶ ↑
Prerequisites¶ ↑
First you must install and configure uri-nodejs-download on your machine.
- [node-install]
-
Install¶ ↑
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:
$ npm init -y
You can now install the dependencies:
$ npm i --save asciidoctor@^2.0 @asciidoctor/reveal.js
Convert AsciiDoc into slides¶ ↑
Once the dependencies are installed, verify that the `asciidoctor-revealjs` command is available. On Linux and macOS, open a terminal and type:
$ npx asciidoctor-revealjs --version
On Windows, open PowerShell and type:
$ .\node_modules\.bin\asciidoctor-revealjs.cmd --version
The command should report the
Asciidoctor
CLI version in the terminal:- source,console
Asciidoctor.js 2.0.3 (
Asciidoctor
2.0.9) [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
Title Slide¶ ↑
Slide One¶ ↑
-
Foo
-
Bar
-
World
To convert the sample presentation into slides, open a terminal and type:
$ npx asciidoctor-revealjs presentation.adoc
On windows, open PowerShell and type:
$ .\node_modules\.bin\asciidoctor-revealjs.cmd 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!
Standalone Executable¶ ↑
Pre-built binary packages can be downloaded from our {uri-project-repo}/releases[GitHub release page]. We provide them for Windows 64-bit, Linux 64-bit and macOS 64-bit. Open an issue if your platform isn't supported. The executables are built using the <<Node / JavaScript Setup,Node / JavaScript>> toolchain.
Install¶ ↑
-
{uri-project-repo}/releases[Download the executable] for your platform and make it executable with `chmod` or using the files properties' user interface.
-
Copy or clone the reveal.js presentation framework in the directory where you will build your slidedeck. Here we do a shallow clone of the repo:
$ git clone -b 3.9.2 –depth 1 github.com/hakimel/reveal.js.git
Convert AsciiDoc into slides¶ ↑
Open a terminal where the executable is and type:
$ ./asciidoctor-revealjs --version
The command should report the
Asciidoctor
reveal.js andAsciidoctor
CLI version in the terminal:- source,console
Asciidoctor
reveal.js 3.0.1 using Asciidoctor.js 2.0.3 (Asciidoctor
2.0.9) [asciidoctor.org] Runtime Environment (node v12.13.1 on linux) CLI version 3.1.0
If you don't have an existing presentation, you can create a sample presentation named [.path]presentation.adoc:
.presentation.adoc
- source,asciidoc
Title Slide¶ ↑
:revealjsdir: reveal.js
Slide One¶ ↑
-
Foo
-
Bar
-
World
To convert the sample presentation into slides, open a terminal and type:
$ ./asciidoctor-revealjs presentation.adoc
The above command will generate a file named [.path]presentation.html. You can open this file in a browser.
Syntax Examples¶ ↑
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¶ ↑
-
Foo
-
Bar
-
World
Slide Two¶ ↑
A Great Story
- .notes
-
-
-
-