Usage

rst2html5slides extends rst2html5 to generate a deck of slides from a reStructuredText file that can be used with any web presentation framework such as impress.js, jmpress.js or deck.js.

rst2html5slides source is located at http://bitbucket.org/andre_felipe_dias/rst2html5slides but you can install it with pip:

$ pip install rst2html5slides

Later, you will also need to install or download the chosen web presentation framework. For now, let’s concentrate on making presentations.

Important

Before proceeding, it is important that you already know reStructuredText basic syntax. I’d like to suggest two links:

Making Presentations

By default, every section of a reStructuredText (rst) document becomes a slide. A typical presentation in reStructuredText (rst) has the following pattern:

Topic 1
=======

* Item A
* Item B


Topic 2
=======

* Item C
* Item D

When converted by rst2html5slides, the result is:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
</head>
<body>
<deck>
    <slide id="topic-1">
        <header>
            <h1>Topic 1</h1>
        </header>
        <section>
            <ul>
                <li>Item A</li>
                <li>Item B</li>
            </ul>
        </section>
    </slide>
    <slide id="topic-2">
        <header>
            <h1>Topic 2</h1>
        </header>
        <section>
            <ul>
                <li>Item C</li>
                <li>Item D</li>
            </ul>
        </section>
    </slide>
</deck>
</body>
</html>

Note

Note that both <deck> and <slide> are custom HTML tags. The former wraps all slides while the latter wraps each slide. You can style and select them in CSS and Javascript but you also can change them if prefer or need to adapt your presentation to a framework or stylesheet.

A rst section is initiated by a title of any level, but in rst2html5slides, only sections from the highest level become slides:

Slide 1
=======

Slide contents

Slide 2
=======

Subtitle
--------

* item A
* item B

will be translated to:

...
<body>
<deck>
    <slide id="slide-1">
        <header>
            <h1>Slide 1</h1>
        </header>
        <section>Slide contents</section>
    </slide>
    <slide id="slide-2">
        <header>
            <h1>Slide 2</h1>
            <h2>Subtitle</h2>
        </header>
        <section>
            <ul>
                <li>item A</li>
                <li>item B</li>
            </ul>
        </section>
    </slide>
</deck>
</body>
</html>

You are not limited to section titles, paragraphs and lists. All other reStructuredText constructs are available to your presentation such as images, tables, code-blocks etc.

Untitled Slides

Sometimes, you might want an untitled slide. This can be accomplished using a transition marker:

Untitled slide 1

----

Untitled slide 2

----

Untitled slide 3

which becomes:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
</head>
<body>
<deck>
    <slide>
        <section>Untitled slide 1</section>
    </slide>
    <slide>
        <section>Untitled slide 2</section>
    </slide>
    <slide>
        <section>Untitled slide 3</section>
    </slide>
</deck>
</body>
</html>

Some Useful reStructuredText Directives to Presentations

reStructuredText has two useful directives to register some document metadata directly into the HTML head section: title and meta:

.. title:: My Presentation Title
.. meta::
    :author: André Felipe Dias
    :keywords: mercurial, web presentation, rst2html5slides

which translates to:

<!DOCTYPE html>
<html>
<head>
    <title>My Presentation Title</title>
    <meta charset="utf-8" />
    <meta content="André Felipe Dias" name="author" />
    <meta content="mercurial, web presentation, rst2html5slides" name="keywords" />
</head>
<body></body>
</html>

Another important directive is class, which sets the “class” attribute value on its content or on the first immediately following non-comment element. When making presentations, you use class directive to set the class of a slide:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
.. class:: logo-background

Topic X
=======

paragraph


.. class:: section-title

----

New Chapter

Topic Y
=======

.. class:: hint

* This also works
* Substructure here

which translates to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
...
<deck>
    <slide class="logo-background" id="topic-x">
        <header>
            <h1>Topic X</h1>
        </header>
        <section>paragraph</section>
    </slide>
    <slide class="section-title">
        <section>New Chapter</section>
    </slide>
    <slide id="topic-y">
        <header>
            <h1>Topic Y</h1>
        </header>
        <section>
            <ul class="hint">
                <li>This also works</li>
                <li>Substructure here</li>
            </ul>
        </section>
    </slide>
</deck>
...

Slide Attributes

Slide attributes are set via rst fields declared just above the desired slide. There is no restriction on field name or value. They are directly included as slide tag attributes. Example:

:id: Opening
:data-x: 1000
:data-y: 500
:data-scale: 3

Presentation Opening

resulting in:

...
<deck>
    <slide data-y="500" data-x="1000" id="Opening" data-scale="3">
        <section>Presentation Opening</section>
    </slide>
</deck>
...

Manual Positioning of Slides

You can position slides manually through data-* attributes which are used by impress.js and jmpress.js to set the position/zoom/rotation of a slide. The most common fields are:

  • data-x: The horizontal position of a slide in pixels. Can be negative.
  • data-y: The vertical position of a slide in pixels. Can be negative.
  • data-z: This controls the position of the slide on the z-axis. Setting this value to -3000 means it’s positioned -3000 pixels away. This is only useful when you use data-rotate-x or data-rotate-y, otherwise it will only give the impression that the slide is made smaller, which isn’t really useful.
  • data-scale: Sets the scale of a slide, which is what creates the zoom. Defaults to 1. A value of 4 means the slide is four times larger. In short: Lower means zooming in, higher means zooming out.
  • data-rotate-x: The rotation of a slide in the x-axis, in degrees. This means you are moving the slide in a third dimension compared with other slides. This is generally cooll effect, if used right.
  • data-rotate-y: The rotation of a slide in the x-axis, in degrees.
  • data-rotate-z: The rotation of a slide in the x-axis, in degrees. This will cause the slide to be rotated clockwise or counter-clockwise.
  • data-rotate: The same as data-rotate-z.

Unless there is an automatic distribution function defined, the same set of data-* attributes are applied to the following slides until you overwrite some of their values. For example:

:data-x: 1000
:data-y: 1000

slide 1

:data-x: 2000

----

slide 2

:data-y: -1000

----

slide 3

results in:

...
<deck>
    <slide data-x="1000" data-y="1000">
        <section>slide 1</section>
    </slide>
    <slide data-x="2000" data-y="1000">
        <section>slide 2</section>
    </slide>
    <slide data-x="2000" data-y="-1000">
        <section>slide 3</section>
    </slide>
</deck>
...

Note that slide 2 kept the same data-y value from slide 1 and slide 3 has the same data-x value from slide 2.

Attention

Positional attributes must be declared above the desired slide. So, :data-x: 2000 refers to slide 2 while :data-y: -1000 changes slide 3.

Automatic Positioning of Slides

Manual positioning is annoying if all you need is a simple presentation. In such cases, you should use one of the automatic distribution functions provided by rst2html5slides. For the time being, there are three functions available:

  1. linear: horizontal distribution by regular increments of data-x.
  2. grid: similar to linear, but a new line is created at every 4 slides. This number can be changed passing an additional parameter.
  3. grid_rotate: similar to grid, but the slide is rotated in 180 degrees when line changes.

To define an automatic positioning function, use a presentation directive at the beginning of the presentation:

.. presentation
    :distribution: grid 2

slide 1

----

slide 2

----

slide 3

which translates to:

...
<deck>
    <slide data-x="0">
        <section>slide 1</section>
    </slide>
    <slide data-x="1600">
        <section>slide 2</section>
    </slide>
    <slide data-y="1600" data-x="0">
        <section>slide 3</section>
    </slide>
</deck>
...

Tip

grid 1 makes a column.

Increment Values

The default value for increment data-x and data-y is 1600. To change this, specify different values with increment attribute declaring one or two values (see the next section for an example). A single value will be applied to both data-x and data-y.

Interfering on Automatic Positioning

Even using automatic positioning, you can change the position of one slide setting some data-* attributes. The automatic distribution will restart from this slide.

Example:

.. presentation::
    :distribution: grid_rotate 2
    :increment: 1000 800

slide 1

:data-x: -500
:data-y: -1000
:data-scale: 3
:data-rotate-z: 90

----

The automatic positioning restarts at this slide
due to its custom positioning

----

Same line yet

----

New line, with rotation

resulting in:

...
<deck>
    <slide data-x="0" data-rotate-z="0">
        <section>slide 1</section>
    </slide>
    <slide data-y="-1000" data-x="-500" data-rotate-z="90" data-scale="3">
        <section>The automatic positioning restarts at this slide due to its custom positioning</section>
    </slide>
    <slide data-y="-1000" data-x="500" data-rotate-z="90" data-scale="3">
        <section>Same line yet</section>
    </slide>
    <slide data-y="-200" data-x="500" data-rotate-z="269.9" data-scale="3">
        <section>New line, with rotation</section>
    </slide>
</deck>
...

Adapting to a Presentation Framework

Each presentation framework has its particularities or choices regarding style and structure of slides, but it is not always necessary to change the structure of a raw rst2html5slides translation. For example, jmpress.js is rather flexible. You could configuring it to accept a deck tag as the root element and slide tags as steps:

$(function() {
    $('deck').jmpress({
        stepSelector: 'slide'
    });
});

rst2html5slides translations can also be used unchanged in deck.js:

$(function() {
    $.deck("slide");
});

Adjusting Presentation Structure

You might want to change the rst2html5slides default structure to adapt its result to a framework structure or to an existent style. For example, impress.js expects a presentation strictly follow the structure:

<body>
    <div id="impress">
        <div class="step">
            ...
        </div>
        <div class="step">
            ...
        </div>
        ...
    </div>
</body>

rst2html5slides result structure can be configured by --deck-selector and --slide-selector parameters or by a presentation directive with deck_selector and slide_selector options. To configure rst2html5slides to conform to impress.js you can use:

$ rst2html5slides --deck-selector 'div#impress' --slide-selector 'div.step' ...

or

.. presentation::
    :deck_selector: div#impress
    :slide_selector: div.step

Tip

Follow the CSS selector format to specify tag, class and id.

Templates

Just changing HTML structure isn’t enough. You also need to include all framework files in presentations. One way is passing parameters to rst2html5slides:

  • --script
  • --script-defer
  • --stylesheet

Example:

$ rst2html5slides.py \
    --stylesheet jmpress.css \
    --script http://code.jquery.com/jquery-latest.min.js \
    --script jmpress.js \
    --script-defer jmpress_init.js \
    --deck-selector '#jmpress' \
    example.rst example.html

However, the simplest way is through templates where all necessary links, scripts and even additional constructs are already declared and the job of rst2html5slides is just filling in the contents of the presentation. Example:

<!DOCTYPE html>
<html {html_attr}>
<head>
    <!-- styles and scripts for a jmpress.js presentation -->
    <meta content="width=device-width, maximum-scale=1.0, initial-scale=1.0, user-scalable=yes" name="viewport" />
    <link href="css/jmpress.css" rel="stylesheet" />
    <link href="css/default.css" rel="stylesheet" />
    <link href="css/pygments.css" rel="stylesheet" />
    <script src="http://code.jquery.com/jquery-latest.min.js"></script>
    <script src="js/jmpress.js"></script>
    <script src="js/jmpress_init.js" defer="defer"></script>
    {head}
<body>{body}
<div class="hint">
    <p>Use a spacebar or arrow keys to navigate</p>
</div>
</body>
</html>
$ rst2html5slides --template jmpress_template.html example.rst example.html