Skip to content

Advanced usage

Jump to bottom
Nguyen Hoang Duong edited this page Oct 10, 2019 · 18 revisions

Advanced usage

Hey there! The purpose of this page is to give you a complete documentation on using reveal-init's advanced options - which are the options that haven't been introduced in the Getting Started page. If you haven't read that page, you may want to do so first before reading this wiki page.

Table of Content

  1. Before you start
  2. Setting the presentation's title
  3. A special value for --header
  4. Importing all themes
  5. Importing files in REVEAL_PATH/lib
  6. Tab length preference
  7. Initiating your project as a Git repository
  8. Empty slides
  9. Temporary REVEAL_PATH
  10. Conclusion
  11. What's next?

Before you start

It is preferred to learn by doing, so before we begin, start by creating a directory named "Slides" in your home directory. You can do so by using your favorite file manager (like Nautilus or Dolphin), or by using mkdir in the command line:

mkdir ~/Slides

Feel free to name the directory anything other than "Slides", but the name "Slides" will be used throughout this page.

Now move to the directory you just created:

cd ~/Slides

Setting the presentation's title

A Reveal.js slide deck is essentially a web page. And like any other web page, it may have a title, which is declared by the HTML's <title> tag. The title is normally displayed in the web browser's tab.

To set a title for your slide deck, use the -t option (or its longer equivalence, --title):

reveal-init --title "WebGL and its power | Adam M." webgl

If you peek inside webgl/index.html, you should see that there's the <title> tag inside <head>:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

        <title>WebGL and its power | Adam M.</title>

And if you view the slide deck using a web browser, you should see the title in the browser's tab.

Now delete the webgl directory and move on.

rm -r webgl

A special value for --header

As previously introduced in the Getting Started wiki page, the --header option creates the slide deck's first slide and adds a level-1 header to that slide. Often times, the header's text content is the same as the title. In that situation, you do not have to type the text twice; you can pass the string "_TITLE" to the --header option.

reveal-init --title "WebGL and its power" --header _TITLE -f league webgl

As you can see, the text "WebGL and its power" appears as both the title (as seen in the browser's tab) and the header (as seen in the first slide). The header appears to be capitalized, but that's what the League theme's CSS does to it, so it's okay.

Notes:

  • There's no special value for --title. That means you cannot do something like --title _HEADER to achieve the same effect.
  • If you set "_TITLE" as the value for the --header option, yet does not invoke the --title option, the --header option won't make any effect, or in other words, no header for you.

Importing all themes

When you haven't yet decided on a theme for your slide deck or you want to switch between many themes (e.g. with the help of a plugin like Menu), you might want to import all of the themes instead of just one. To import all themes, just specify "all" as the value for the -f option:

reveal-init -f all deck-02

Note: Importing a theme means copying the theme's CSS file and its SCSS source.

Importing files in REVEAL_PATH/lib

The Reveal.js project directory structure contains a lib directory, where third-party source files (e.g. jQuery, Font Awesome) are stored. Before the first pre-release of reveal-init 3.0 was released, it was impossible to manually choose what to import from the lib directory of REVEAL_PATH: reveal-init would copy the entire directory. Fortunately, this is no longer a problem with reveal-init 3.0 Alpha and later versions, thanks to the --lib option. Its general usage is as follows:

reveal-init --lib FILE_1 FILE_2 ... -

The syntax is pretty much similar to that of the --plugin option. The path for FILE_1, FILE_2 and so on must be relative to the REVEAL_PATH/lib directory. Let's do a simple example to see what that means.

  1. First, let's see what (directories) we can import from REVEAL_PATH by running:
tree -d "$REVEAL_PATH/lib"

The official Reveal.js repository has some files included in $REVEAL_PATH, which if we run the above command with it we'll get something like this as the result:

/home/octo/Forks/reveal.js/lib
├── css
├── font
│   ├── league-gothic
│   └── source-sans-pro
└── js
  1. Let's import the js and font directories in REVEAL_PATH/lib. To do that, run:
reveal-init --lib js font - deck-03

Here, we've specified that js/ and font/ shall be the directories that we want to import. Note how you only have to put "js" and "font", which are paths relative to REVEAL_PATH/lib (in other words, they're "REVEAL_PATH/lib/js" and "REVEAL_PATH/lib/font" with the "REVEAL_PATH/lib/" part removed).

  1. Verify that we've indeed imported the js and font directories. Running:
ls ~/Slides/deck-03/lib/

should give us:

font  js

When you specify a directory to --lib, reveal-init will import everything in that directory (i.e. its sub-directories and files inside). You can see that by yourself using the tree utility:

tree ~/Slides/deck-03/lib/
/home/octo/Slides/deck-03/lib/
├── font
│   ├── league-gothic
│   │   ├── league-gothic.css
│   │   ├── league-gothic.eot
│   │   ├── league-gothic.ttf
│   │   ├── league-gothic.woff
│   │   └── LICENSE
│   └── source-sans-pro
│       ├── LICENSE
│       ├── source-sans-pro.css
│       ├── source-sans-pro-italic.eot
│       ├── source-sans-pro-italic.ttf
│       ├── source-sans-pro-italic.woff
│       ├── source-sans-pro-regular.eot
│       ├── source-sans-pro-regular.ttf
│       ├── source-sans-pro-regular.woff
│       ├── source-sans-pro-semibold.eot
│       ├── source-sans-pro-semibolditalic.eot
│       ├── source-sans-pro-semibolditalic.ttf
│       ├── source-sans-pro-semibolditalic.woff
│       ├── source-sans-pro-semibold.ttf
│       └── source-sans-pro-semibold.woff
└── js
    ├── classList.js
    ├── head.min.js
    └── html5shiv.js

4 directories, 22 files
  1. It is easy to further cut out the files you don't need! Let's import REVEAL_PATH/lib/font/source-sans-pro, REVEAL_PATH/lib/font/league-gothic/league-gothic.css, and REVEAL_PATH/lib/js/head.min.js. To do so, just be more specific:
reveal-init --lib font font/source-sans-pro font/league-gothic font/league-gothic/league-gothic.css js js/head.min.js - deck-04

Note that if you want to import a file in lib, you also have to write the paths of all parent directories of that file. In the above example, we wanted to import REVEAL_PATH/lib/font/league-gothic/league-gothic.css, a CSS file. Thus the arguments we passed to the --lib option had to have font and font/league-gothic.

  1. Verify that you've indeed imported the files needed
tree ~/Slides/deck-04/lib/
/home/octo/Slides/deck-04/lib/
├── font
│   ├── league-gothic
│   │   └── league-gothic.css
│   └── source-sans-pro
│       ├── LICENSE
│       ├── source-sans-pro.css
│       ├── source-sans-pro-italic.eot
│       ├── source-sans-pro-italic.ttf
│       ├── source-sans-pro-italic.woff
│       ├── source-sans-pro-regular.eot
│       ├── source-sans-pro-regular.ttf
│       ├── source-sans-pro-regular.woff
│       ├── source-sans-pro-semibold.eot
│       ├── source-sans-pro-semibolditalic.eot
│       ├── source-sans-pro-semibolditalic.ttf
│       ├── source-sans-pro-semibolditalic.woff
│       ├── source-sans-pro-semibold.ttf
│       └── source-sans-pro-semibold.woff
└── js
    └── head.min.js

4 directories, 16 files

Note: reveal-init has notable bugs and limitations in importing lib files until the stable release of version 3.0.

Tab length preference

By default, reveal-init uses 4-space tabs when creating index.html. If you prefer 2-space tabs, invoke --short-tab.

There's also an inverse, which is --long-tab, that tells reveal-init to use 4-space tabs. This makes --long-tab seem to be redundant because reveal-init uses 4-space tabs by default, but there is a trick behind it. See Tricks.

Initiating your project as a Git repository

If you want to start your Reveal.js presentation project as a Git repository, use the --git option. :octocat:

Empty slides

Sometimes, you need to create a presentation that you've already known how many slides will be in the slide deck. Here's an example.

Example situation

A student is asked to present her thoughts on a recent global event. So she decides to use a slide deck to aid her presentation. And that's going to be a Reveal.js slide deck of course. She comes up with a plan for the slide deck as follows:

  • There must be an "intro" slide and an "outro" slide, so that's 2.
  • The opinion is introduced in 1 slide.
  • The student has 3 arguments to argue that her opinion is legit. Each argument is begun by an introducing slide and a following slide that shows the argument in details. So that's 6 slides.
  • Conclusion in 1 slide.
  • The student has a quote from a prominent figure involved in the event and wants to present it in a separated slide, so that's another slide for it.

So it appears that the slide deck is going to contain 11 slides.

In that situation, the -n option might help. -n allows you to generate as many empty slides as you want. The option must be followed by a whole number, which is the input value for the option. Try running this, for example, to generate a slide deck with 10 empty slides.

reveal-init -n 10 -f sky --header "My point of view" my_view

View the new slide deck in a graphical web browser. There should be 11 slides in total, the first slide being non-empty (as it includes a header) followed by 10 empty slides.

Note: In a Reveal.js slide deck, there can be vertical slides, but reveal-init can only create horizontal slides.

Note: The -n option might seem to be a redundant option, as you can create slides on your own by adding <section> tags. Well, that's why -n wasn't introduced earlier in the tutorial.

Temporary REVEAL_PATH

If you ever need to use a different path as REVEAL_PATH temporarily, don't even think about re-exporting the REVEAL_PATH variable! The -d option is already there.

  1. Copy the fine clone of Reveal.js to another directory in your home directory & name it "reveal.js-test"
cp -r $REVEAL_PATH ~/reveal.js-test
  1. Remove the js directory in ~/reveal.js-test 
rm -r ~/reveal.js-test/js
  1. Run reveal-init with the -d option to create a new slide deck taking ~/reveal.js-test as REVEAL_PATH 
reveal-init -d ~/reveal.js-test deck-05

You should see something like this printed on the terminal, otherwise something is wrong with reveal-init:

REVEAL_PATH: /home/octo/reveal.js-test
ERROR   $REVEAL_PATH/js/reveal.js not found
FATAL   Fix the above problem(s) and try again
Log messages can be found in /tmp/reveal-init-te8ShKuH

reveal-init yields an error because reveal.js is missing. That's because you deleted the js directory in ~/reveal.js-test earlier, and reveal.js is normally located in that directory.

A Reveal.js slide deck needs reveal.js to work. That's why reveal-init does not create any new slide deck if reveal.js is missing.

  1. Run reveal-init again, but without the -d option
reveal-init deck-05

A new slide deck has been generated at deck-05. This shows that the -d option indeed sets REVEAL_PATH temporarily.

Conclusion: The example above shows that -d is handy in testing reveal-init.

Conclusion

You've reached the end of this wiki page. With all the options and features of reveal-init in mind, you should now be able to make extensive use of reveal-init to achieve more and to be more productive as a happy Reveal.js user. Feel free to leave the wiki and move on, or get to know some tricks that are possible with reveal-init by reading Tricks.

P.S. Don't forget to delete ~/Slides and ~/reveal.js-test.

What's next?

Clone this wiki locally