revelry v2.0.0
Revelry
Revelry is a project builder for Reveal.js.
If you make a lot of presentations with Reveal, you will find yourself unnecessarily duplicating huge chunks of boilerplate. With Revelry you can concentrate on your presentation content and let Revelry take care of the rest.
This is an alpha release. See the issues tracker for the list of planned features and known issues.
Installing
$ npm install -g revelry
Note: if you are cloning this repo and installing locally, you will need to
specify the --unsafe-perm
option to npm install
. This is because the
postinstall needs access to the reveal.js dependency.
Alternative: Using Docker
If you have Docker installed, you can use Revelry without needing to install anything. For example:
$ docker run -v $(pwd):/work -u $(id -u) fishpercolator/revelry new myproject
Or create an alias:
$ alias revelry='docker run -v $(pwd):/work -u $(id -u) fishpercolator/revelry'
Creating a project
$ revelry new myproject
$ revelry new myproject -t "My amazing presentation" -d "A short description of my presentation"
The anatomy of a Revelry project
myproject/
Revfile.json
slides.html
img/
custom/
custom.css
header.html
Revfile.json is where all the configuration for your presentation goes. In here you can specify the title and description as well as Reveal options such as theme and plugins. (Note: Revfile.json is really JavaScript code, rather than JSON, so you can include functions and other complex types in here. The usual warnings about editing executable code apply.)
slides.html is a Handlebars-enabled
HTML file containing your slides. Each slide is given an HTML
<section>
. The contents of Revfile.json
are used as the
Handlebars context.
img/ is a directory where you can put images you need for your
presentation. Its contents will be copied to the built site's img/
dir when your project is built.
custom/ contains files that can be used to override some of the default HTML and CSS provided by Reveal. (See below.)
Example slides.html
<section>
<h1>{{title}}</h1>
<h2>{{description}}</h2>
</section>
<section>
<h2>My first slide</h2>
<ul>
<li class="fragment">Bullet one</li>
<li class="fragment" style="color:red">Bullet two</li>
</ul>
</section>
Partials
You can break your presentation into multiple files, which can be a mixture of Handlebars and Jade. Then you can include them in each other using each language's native include syntax. For example:
<section>
<h1>Handlebars example</h1>
</section>
{{! Include intro.html or intro.jade}}
{{> intro}}
section
h1 Jade example
//- Include another Jade file
include intro.jade
//- Include a Handlebars file
include:handlebars intro.html
Building
Once you have filled out the contents of Revfile.json
and slides.html
,
you can build your project.
$ cd myproject/
$ revelry build
By default this will create the project in a .gitignored subdirectory
www
of the project directory, but you can specify any target
directory:
$ revelry build /var/www/myproject
Configuration
Most of the configuration of a Revelry project happens in the
Revfile.json
. Some of the supported keys are:
- title: The presentation title.
- description: A description of your presentation (used in the meta tags).
- author: The author's name (used in the meta tags).
- options: Overrides for the options passed to the Reveal.js constructor. All the Reveal.js options are available here for override. (Note: The 'theme' option is special, because it affects which CSS file is loaded in your presentation's header.)
- plugins: See below.
Plugins
Including a plugin name in the plugins array of Revfile.json
will
cause the appropriate files to be copied to the built project from
Reveal.js and the necessary JavaScript files loaded as dependencies.
If you want to configure the plugin further, you'll need to add the config separately to options. See the Reveal.js documentation for more details.
Currently supported plugins are:
- classList
- highlight
- leap
- markdown
- math
- notes
- notes-server (will cause your presentation to
npm install
so it can be used) - remotes
- zoom
The multiplex plugin is not supported because its configuration is too complicated to automatically guess.
Revelry currently doesn't support any plugins other than the standard ones. Watch out for 3rd-party plugin support in a future release.
Custom CSS / Sass
Add CSS to the custom.scss
file if you want to override the theme's
default CSS or add classes of your own.
The file is preprocessed with Sass, so you can use variables, nested selectors, etc. if you wish.
Note that you'll need to put all your overrides inside the .reveal
class, like this:
.reveal {
h1 {
color: black;
}
}
Custom header
If you need to insert any additional info into the HTML header (such
as meta tags or links to CSS or RSS), you can edit the header.html
file. The contents of this file will be inserted into the
<head>
of the presentation.
You can also set any of the <meta>
tags using the meta
object in
Revfile.json
. If you don't have one because your project was created by an
older version, run revelry upgrade
on your project to bring it up to date.
Custom footer
Added in 2.0.0. This contains the code to initialize Reveal.js and any custom JavaScript you want to add to your presentation.
If you have a project that was created before 2.0.0, you'll need to run
revelry upgrade
to create this file before you can build.
Jade support
Revelry also supports templates in Jade format, which is a more concise language than HTML and lends itself quite well to writing presentations.
If you have a slides.jade
instead of slides.html
, it will be
parsed as a Jade file.
You can also create a new Jade project outright, e.g.:
$ revelry new myproject --jade
The Revfile context will be passed to Jade as locals, so you can use its values the same way you would in Handlebars.
The earlier example, expressed as Jade, is:
section
h1= title
h2= description
section
h2 My first slide
ul
li.fragment Bullet one
li.fragment(style='color:red') Bullet two
Note: The resulting HTML is still processed by Handlebars.
Author info
Copyright 2014-2015, Fish Percolator.
Released under a BSD-style license.
Fork me on Github: https://github.com/fishpercolator/revelry
Issue tracker: https://github.com/fishpercolator/revelry/issues