Skip to content

Getting Started

Jump to bottom
Nguyen Hoang Duong edited this page Oct 9, 2019 · 41 revisions

Welcome!

I'm glad that you are here. If you still don't get what reveal-init is about or you are not sure how to use it, then you have come to the right place. This page will guide you through reveal-init's most common usages in an understandable language.

This page focuses on explaining how to use reveal-init on UNIX-like operating systems. If you are using Windows, kindly consult this wiki page instead.

Table of Content

  1. What is reveal-init?
  2. Downloading reveal-init
  3. Setup
    1. Getting a Shell installed
    2. Cloning the Reveal.js repository
    3. Setting the REVEAL_PATH environment variable
  4. Using reveal-init: The first steps
    1. Creating a bare-bone slide deck
    2. Setting a theme for your slide deck
    3. Adding the biggest header
    4. Adding plugins
  5. Conclusion
  6. What's next?

What is reveal-init?

reveal-init is essentially a small program that you can run to start a new Reveal.js presentation project.

If you've already known what Reveal.js is, skip.

If you don't know what Reveal.js is, you should probably check it out first. It's an awesome framework that you can use to build a presentation using Web technologies, such as HTML, CSS, JavaScript,...all the things possible on the Web. Reveal.js is beloved by thousands of people and I (@you-create) am one of them.

Some of the presentations made using Reveal.js are:

You can see a lot more here.

A Reveal.js presentation is basically a web page that is designed to look like a presentation slide deck. And just like web projects, Reveal.js presentation projects are stored inside folders in computers. In order to use Reveal.js, you first clone the Reveal.js project (which results in a folder containing the project's files on your computer), and modify the files (such as index.html in order to make your own presentation slides content).

However, the Reveal.js project folder contains a lot of files that you might not want to include in your own presentation project. Such files are, either for testing purposes, or for developers contributing to the Reveal.js project. Those unwanted files are bower.json, package.json, CONTRIBUTING.md, the ones in the test folder,...just to name a few.

As someone who just wants a presentation, you might find it a burden to delete those unnecessary files. Of course, you might leave them alone, but that would consume an amount of data space on your computer, and make your presentation project heavier. I'm sure a lot of people don't want that outcome.

This is where reveal-init kicks in. reveal-init is a program that does the following:

  1. Collect the necessary files from an existing Reveal.js project folder in the user's computer
  2. Make a new folder which serves as a presentation project folder
  3. Put the collected files in the new folder

In short, reveal-init starts a new Reveal.js presentation project for you.

The benefits?

  • It saves your time (i.e. makes you more productive)
  • It saves your energy
  • It saves your disk space

reveal-init is nothing big. It might be a small script among thousands of scripts you run on your computer everyday. But I really hope it will make your life just a bit easier.

With all of that being said, let's begin learning how to get reveal-init running on your computer.

Downloading reveal-init

  1. Visit this page
  2. Click on "reveal-init" (under the "Assets" tab) to download the reveal-init Shell script (as shown in the image below)

  1. If the download went okay, the reveal-init executable Shell script should be now on your computer. Move it to /usr/bin (or /usr/local/bin, or whatever directory in $PATH that you find appropriate)

Setup

reveal-init has the following properties:

  1. It is a Shell script
  2. It copies files from an existing clone of the Reveal.js project files
  3. It relies on an environment variable called "REVEAL_PATH"

The setup process is divided into 3 parts which correspond to those properties:

  1. Getting a Shell installed
  2. Clone the Reveal.js repository
  3. Set the REVEAL_PATH environment variable

Getting a Shell installed

TL;DR: reveal-init is written in bash so make sure you have bash installed.

reveal-init is a program written in Bash, a Shell made for UNIX-like operating systems. Make sure you have Bash installed on your computer in order to run reveal-init with Bash. Most GNU/Linux distributions and the latest macOS releases have Bash installed by default. Just search for and open a terminal window.

If you don't know what terminal is or how command line programs work, you might want to consult the Internet. This wiki page tries to be short. 👍

Cloning the Reveal.js repository

You need to get a copy of the Reveal.js project repository on your computer. This is where reveal-init will copy files from.

There are 2 ways to achieve this:

  1. The GUI way i.e. clicking
  2. The CLI way i.e. typing (for CLI lovers 😉)

The GUI way

  1. Visit this page
  2. Click on "Source code (zip)" to download the ZIP archive of the latest Reveal.js project repository

  1. Using whatever file browser you normally use, go to the location where files you download from the Internet are located (usually the Downloads folder)
  2. Extract the ZIP file (this is a common task that even non-techie can perform)

  1. (optional) Move the folder to another location, wherever you think is appropriate for it (it's not a good computing practice to leave files in the Downloads folder)
  2. (optional) Rename the extracted folder to reveal.js

The CLI way

  1. Using cd, move to a directory where you want to place the Reveal.js repository clone
  2. Clone the Reveal.js repository with
git clone https://github.com/hakimel/reveal.js

Setting the REVEAL_PATH environment variable

So you've got a clone of the Reveal.js repository on your computer. Great! This is where reveal-init will extract files from. But reveal-init has to know where you've placed that clone. reveal-init cannot tell that by itself, nor it has the time to find the clone. This Shell script has to refer to an environment variable called "REVEAL_PATH".

To set a value for REVEAL_PATH (on UNIX-like operating systems):

  1. Open ~/.profile (or create it if you haven't had it yet) using a text editor of your choice
  2. In a new line of Shell script, use export to set a value for REVEAL_PATH. The value for REVEAL_PATH should be the path to the Reveal.js repository clone on your computer. For example, mine is:
export REVEAL_PATH="$HOME/Projects/Forks/reveal.js"
  1. Save the change and close your text editor
  2. Apply the change by running
source ~/.profile

You've finished the setup process! 🎉 🎉 🎉
Now you can start using reveal-init.

Using reveal-init: The first steps

This section is a step-by-step tutorial on how to use reveal-init. All basic options and usages will be introduced.

Creating a bare-bone slide deck

If you are running reveal-init to create a new presentation project, you must let reveal-init know the name of the project directory. You do that by specifying the name of the directory as the last command line argument.

Let's practice by doing. Enter a command line environment (e.g. terminal) and do the following:

  1. Using mkdir, create a new directory in your home directory. For the sake of this tutorial, let's name the directory "Slides". We will use this directory throughout the tutorial.
mkdir ~/Slides

In addition, we assume that the path of the Reveal.js clone is /home/octo/Forks/reveal.js.

  1. Move to the new directory using cd:
cd ~/Slides
  1. Create a new Reveal.js presentation project using reveal-init. Let's name the project directory "barebone". You achieve that by running the following command:
reveal-init barebone

Assuming you've configured everything correctly, you should see the following messages printed by reveal-init:

REVEAL_PATH: /home/octo/Forks/reveal.js
Generated a new slide deck at barebone.

If you instead see error messages (the ones that start with "ERROR" in color red), you may need to consult this wiki page to fix the problem.

Otherwise, you've got reveal-init running successfully! You can view the generated presentation using your web browser. Open ~/Slides/barebone/index.html using your web browser. If your computer is configured to open HTML files using a web browser (perhaps your favorite one), you can use the following command:

xdg-open ~/Slides/barebone/index.html

You should see this in your browser:

Indeed, you see nothing. This is a bare-bone slide deck with nothing in it. In order to get something more visually appealing, we need to know 2 reveal-init command line options that can achieve this:

  • -f which sets a theme for your Reveal.js slide deck
  • --header which creates a slide and places a header in it

Setting a theme for your slide deck

reveal-init has the ability to copy a designated theme's stylesheet file and link index.html to that file. To do that, use the -f command line option. The name of a theme must be specified. For example, if you want the League theme (that is packed within the original Reveal.js repository), run:

reveal-init -f league deck-01

In the above line, "league" is the name of the theme we want. It goes after the argument "-f". Then we, again, specify the project directory name "deck-01" as the last argument.

Side note

Denote the value you pass to -f (that is, the argument that comes after -f) as THEME. reveal-init will then copy the theme by copying its CSS file at $REVEAL_PATH/css/theme/THEME.css. Because the League theme's CSS file is named league.css in the Reveal.js repository, you must specify its name as "league" and not "League" or anything else.

To see valid -f inputs, run:

reveal-init --ls-themes  # works only for reveal-init version 3.0 beta and later

or, for reveal-init version 3.0 alpha and earlier:

find $REVEAL_PATH/css/theme -type f -name "*.css" -exec basename -s .css {} ';'

If everything is done correctly, the message "Generated a new slide deck at deck-01." should appear. View your new slide deck in a web browser of your choice, this is (hopefully) what you will see:

That's the background you get when you use the League theme. Still, our slide deck is visually pretty much empty, so let's add a header to it.

Adding the biggest header

Normally, the first slide in a slide deck contains a big header that suggests the topic that the presenter is going to talk about. For example, if a presenter starts off the slide deck with a slide that looks like this

...then the audience knows that the presenter is going to talk about using Serif fonts in websites. To achieve a big header like that in the first slide, use the --header option. The argument that comes after --header must be the text content of the header. This is an example:

reveal-init -f league --header "Living in Industry 4.0" industry_4

As you can see, there are 5 arguments passed to reveal-init:

  1. "-f": Option
  2. "league": Input to option -f
  3. "--header": Option
  4. ""Living in Industry 4.0"": Input to option --header
  5. "industry_4": Last argument, which is the desired name for the project directory

Here, we again set League as the theme. We also set "Living in Industry 4.0" as the big header that normally appears in the first slide. Go ahead and run the above example in your command line environment.

If you view the new slide deck in your web browser, this is what you'll see:

Adding plugins

reveal-init was also given power to do the following:

  • Copy plugins' folders into the new slide deck's project folder; and
  • Link to the plugins' JavaScript files in index.html

Reveal.js plugins make your slide deck even more awesome, and enhance the audience's experience with your talk. The Reveal.js repository comes with some plugins packed inside it: Highlight.js, Zoom.js, Multiplex,...just to name a few. So let's learn how to automatically add and link plugins with reveal-init. To do that, you use the --plugin option (or in version 1.1 and later, --plugins to avoid the cringe).

Here's how to use the --plugin option:

  1. First, include --plugin as one of the arguments
  2. List the plugins you want to use by specifying their names as arguments after the --plugin argument
  3. End the list with a dash ("-")

Side note

Denote each argument in the list that comes after the --plugin argument as PLUGIN. reveal-init will then copy each plugin by copying its directory at $REVEAL_PATH/plugin/PLUGIN. Capitalization DOES matter (e.g. "coke" and "Coke" are interpreted as 2 different plugins).

To see valid inputs to give as plugins' names, run:

reveal-init --ls-plugins  # works only for reveal-init version 3.0 beta and later

or, for reveal-init version 3.0 alpha and earlier:

find $REVEAL_PATH/plugin -maxdepth 1 -type d -not -name "plugin" -exec basename {} ';'

Let's re-create the "Living in Industry 4.0" slide deck we made in the prior subsection, but now with the Zoom.js plugin:

  1. First, delete the existing industry_4 directory
rm -r ~/Slides/industry_4
  1. Use the same Shell command (in the prior subsection) but with 3 new arguments:
    1. "--plugin": To start listing plugins you want to include
    2. "zoom.js": The (only) plugin you want to include (for the sake of this tutorial)
    3. "-": To end the list
reveal-init -f league --header "Living in Industry 4.0" --plugin zoom-js - industry_4

Run the command, and make sure the Zoom.js plugin is working properly in your new slide deck.

⚠️ Warning: reveal-init 1.0 cannot recognize Zoom.js's main JavaScript file, so the example won't work with reveal-init 1.0. Please use reveal-init 1.1 Alpha and up.

Finally, let's check out an example of making a new Reveal.js slide deck with multiple plugins.

  1. First, delete the existing industry_4 directory
rm -r ~/Slides/industry_4
  1. Then recreate the "Living in Industry 4.0" slide deck, but now with 3 plugins: notes, notes-server, and zoom-js 
reveal-init -f league --header "Living in Industry 4.0" --plugin notes notes-server zoom-js - industry_4

Conclusion

And there you have it. Now that you know how to use reveal-init, don't be afraid to use it the next time you need to make a Reveal.js slide deck. If you have something to suggest, or a relevant story to share, please do. I would love to hear voices from fellow Reveal.js slide decks makers like you.

What's next?

  • Explore the full potential of reveal-init by knowing the Advanced usage
  • Seeing errors? Know how to solve them by reading Errors & warnings
  • Learn some tricks to be even more productive in the terminal
  • reveal-init is in the Public Domain. Learn how to be more ethical as a software developer by reading Supporting the Public Domain

Clone this wiki locally