HOVERCRAFT(1)

📦
version 2.7 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 HOVERCRAFT(1) — Hovercraft! 💖

okay bestie, welcome to the HOVERCRAFT(1) manual. This is literally the whole vibe, and we're about to make your presentation game iconic. No cap, fr fr. 🫶✨💅

✨ NAME ✨

hovercraft — Hovercraft! Documentation

Contents:

🌸 INTRODUCTION 🌸

🎀 GUI tools are limiting

okay so real talk: I used to do presentations with typical slideshow software, like OpenOffice/LibreOffice Impress, but bestie, those tools felt restricted and limiting. I need to do a lot of reorganizing and moving around, and that might mean changing things from bullet lists to headings to text to pictures and back to bullet lists over again. This happens through the whole process. I might realize something that was just a bullet point needs to be a slide, or that a set of slides for time reasons need to be shortened down to bullet points. Much of the reorganization comes from seeing what fits on one slide and what does not, and how I need to pace the presentation, and to some extent even what kinda of pictures I can find to illustrate what I try to say, and if the pictures are funny or not.

Presentation software should give you complete freedom to reorganize your presentation on every level, not only by reorganizing slides.

The solution for me and many others, is to use a text-markup language, like reStructuredText, Markdown or similar, and then use a tool that generates an HTML slide show from that.

Text-markup gives you the convenience and freedom to quickly move parts around as you like.

I chose reStructuredText http://docutils.sourceforge.net/docs/index.html, because I know it and because it has a massive feature set. When I read the documentations of other text-markup langages it was not obvious if they has the features I needed or not.

🌈 Pan, rotate and zoom

The tools that exist to make presentations from text-markup will make slideshows that has a sequence of slides from left to right. But the fashion now is to have presentations that rotate and zoom in and out. One open source solution for that is impress.js http://github.com/bartaz/impress.js.

With impress.js you can make modern cool presentations.

But impress.js requires you to write your presentation as HTML, which is annoying, and the markup isn't flexible enough to let you quickly reorganize things from bullet points to headings etc.

You also have to position each slide separately, and if you insert a new slide in the middle, you have to reposition all the slides that follow.

🚀 Hovercraft!

So what I want is a tool that takes the power, flexibility and convenience of reStructuredText and allows me to generate pan, rotate and zoom presentations with impress.js, without having to manually reposition each slide if I reorganize a little bit of the presentation. I couldn't find one, so I made Hovercraft.

Hovercraft’s power comes from the combination of reStructuredText’s convenience with the cool of impress.js, together with a flexible and powerful solution to position the slides.

There are four ways to position slides:

  1. Absolute positioning: You simply add X and Y coordinates to a slide, in pixels. Doing only this will not be fun, but someone might need it.
  2. Relative positioning to last slide: By specifying x and/or y with with a starting r,you specify the distance from the previous slide. By using this form of positioning you can insert a slide, and the other slides will just move to make space for the new slide.
  3. Relative positiong to any slide: You can reference any previous slide by its id and specify the position relative to it. This will work for all positioning fields. However, you should not use r as a slide id since the positioning might not behave as you expect.
  4. Automatically: If you don’t specify any position the slide will have the same settings as the previous slide. With a relative positioning, this means the slide will move as long as the previous slide moved. This defaults to moving 1600px to the right, which means that if you supply no positions at all anywhere in the presentation, you get the standard slide-to-the-left presentation.
  5. With an SVG path: In this last way of positioning, you can take an SVG path from an SVG document and stick it into the presentation, and that slide + all slides following that has no explicit positioning will be positioned on that path. This can be a bit fiddly to use, but can create awesome results, such as positioning the slides as snaking Python or similar.

Hovercraft! also includes a presenter console that will show you your notes, slide previews and the time, essential tools for any presentation.

⌨️ Shortcut/Navigation Keys:

A help popup appears upon launching a presentation; it shows the keyboard shortcuts.

  • H -> Toggle the help popup
  • Right, Down, Page Down, Space -> Next slide
  • Left, Up, Page Up -> Previous slide
  • G -> Go to slide
  • P -> Open presenter console

🚀 USING HOVERCRAFT!

You can either use Hovercraft! to generate the presentation as HTML in a target directory, or you can let Hovercraft! serve the presentation from its builtin webserver.

The latter have several benefits. One is that most webbrowsers will be very reluctant to open popup-windows from pages served from the file system. This is a security measure which can be changed, but it's easier to just point the browser to http://localhost:8000 instead.

The second benefit is that Hovercraft! will monitor the source files for the presentation, and if they are modified Hovercraft! will generate the presentation again automatically. That way you don't have to run Hovercraft! everytime you save a file, you only need to refresh the browser.

🎛️ Parameters

hovercraft [-h] [-t TEMPLATE] [-c CSS] [-j JS] [-a] [-s] [-n] [-p PORT]
<presentation> [<targetdir>]

Positional arguments:

  • <presentation> — The path to the reStructuredText presentation file.
  • <targetdir> — The directory where the presentation is saved. Will be created if it does not exist. If you do not specify a targetdir Hovercraft! will instead start a webserver and serve the presentation from that server.

Optional arguments:

  • -h, --help — Show this help.
  • -t TEMPLATE, --template TEMPLATE — Specify a template. Must be a .cfg file, or a directory with a template.cfg file. If not given it will use a default template.
  • -c CSS, --css CSS — An additional CSS file for the presentation to use. See also the :css: settings of the presentation.
  • -j JS, --js JS — An additional Javascript file for the presentation to use. Added as a js-body script. See also the :js-body: settings of the presentation.
  • -a, --auto-console — Open the presenter console automatically. This is useful when you are rehearsing and making sure the presenter notes are correct. You can also set this by having :auto-console: true first in the presentation.
  • -s, --skip-help — Do not show the initial help popup. You can also set this by having :skip-help: true first in the presentation.
  • -n, --skip-notes — Do not include presenter notes in the output.
  • -p PORT, --port PORT — The address and port that the server uses. Ex 8080 or 127.0.0.1:9000. Defaults to 0.0.0.0:8000.
  • --mathjax MATHJAX — The URL to the mathjax library. (It will only be used if you have rST math:: in your document)
  • -N, --slide-numbers — Show the current slide number on the slide itself and in the presenter console. You can also set this by having slide-numbers: true in the presentation preamble.
  • -v, --version — Show program's version number and exit

🎤 Presenter Console

The presenter console feature is designed for showing an annotated version of the presentation on the local laptop display, while showing the presentation itself on a projector.

To use this feature, open the presentation in a browser, and press p. A new browser tab will be created, and the browser focus will switch to that tab automatically. At this point, the two tabs are linked, and the slide navigation controls will affect both tabs.

Now, you'll need to move the presenter console tab into its own browser window. With Firefox, right-click on the tab title, and click on Move Tab --> Move to New Window. With Chromium, drag the tab title down and the tab will be moved into a new browser window.

Finally, drag the presentation window onto the projector's part of the desktop, and press F11 to make the presentation fullscreen.

🧁 Built in templates

There are two templates that come with Hovercraft! One is called default and will be used unless you specify a template. This is the template you will use most of the time.

The second is called simple and right now it only lacks the Goto function. You can ignore it.

🎨 MAKING PRESENTATIONS

📝 A note on terminology

Traditionally a presentation is made up of slides. Calling them "slides" is not really relevant in an impress.js context, as they can overlap and doesn't necessarily slide. The name "steps" is better, but it's also more ambiguous. Hence impress.js uses the terms "slide" and "step" as meaning the same thing, and so does Hovercraft!

💅 Hovercraft! syntax

Presentations are reStructuredText files. If you are reading this documentation from the source code, then you are looking at a reStructuredText document already.

It's fairly simple, you underline headings to mark them as headings:

This becomes a h1
=================

And this a h2
-------------

The different ways of underlining them doesn't mean anything, instead the order of them is relevant, so the first type of underline encountered in the file will make a level 1 heading, the second type a level 2 heading and so on. In this file = is used for level 1, and - for level 2.

You can also mark text as italic or bold, with single asterixes or double asterixes respectively.

You can also have bullet lists:

* Bullet 1

  * Bullet 1.1

* Bullet 2

* Bullet 3

And numbered lists:

1. Item 1

    1.1. Item 1.1

2. Item 2

3. Item 3

You can include images:

.. image:: path/to/image.png
    :height: 600px
    :width: 800px

As you see you can also specify height and width and loads of other parameters http://docutils.sourceforge.net/docs/ref/rst/directives.html#images, but they are all optional.

You can also include videos:

.. raw:: html

...or if it's giving audio energy, same ritual:

.. raw:: html

    <audio controls>
        <source src="./path/to/your/audio.mp3" type="audio/mpeg">
        Your browser does not support the audio element.
    </audio>

You can also flag text as preformatted, bestie. Two ways: end the row above with double colons, or just drop a row of double colons all by itself:

::

    This code here will be preformatted
     and shown with a  monospaced font
    and    all    spaces     preserved.

And if you wanna flex actual source code (with the pretty rainbow letters), that's the code directive:

.. code:: python

    def some_example_code(foo):
        return foo * foo

The syntax highlighting is handled by [Pygments](http://pygments.org/) and it supports lots and lots of languages — genuinely so many — over at [the lexers docs](http://pygments.org/docs/lexers/).

Also you're gonna want a title on the whole presentation, obviously. Drop a .. title:: statement before the first slide:

.. title:: This is the presentation title

Okay so that's the big stuff you need to know about reStructuredText for presentations. There is so much more — advanced features like links, footnotes, the whole menu. It's genuinely advanced enough that you can write a whole [book](http://python3porting.com/) in it 😭 but for all that you'll want to hit up the [documentation](http://docutils.sourceforge.net/docs/index.html).

Presenter notes 🫶

Wanna add presenter notes that show up in the presenter console? Here's the syntax, no cap:

.. note::

    Here goes the presenter note.

External files 🎀

Any image file referenced in the presentation by a relative path gets copied to the target directory, and it keeps its relative path to the presentation. Same goes for images or fonts referenced inside any CSS files used by the presentation or the template.

Images or fonts referenced by absolute paths or URI's? Yeah no, those do not get copied. Periodt.

Styling your Presentation 💅

The CSS that comes bundled in the default template is:

  • highlight.css — has a default style for code syntax highlighting, because doing that by hand would be so much work. If you don't vibe with the default colors or styles in the highlighting, this is the file you should copy and modify.
  • hovercraft.css — contains only the bare minimum: it hides the impress.js fallback message, hides the presenter notes, and sets a useful default of having a step width be 1000 pixels wide.

So basically, you wanna bring your own CSS to style your slides. To include a CSS file, add a :css:-field at the top of the presentation:

:css: css/presentation.css

You can also optionally specify that the CSS should only apply to certain CSS media:

:css-screen,projection: css/presentation.css
:css-print: css/print.css

You can specify any number of CSS files this way. And you can also add one extra CSS-file via a command-line parameter:

hovercraft --css=my_extra.css presentationfile.rst outdir/

Styling the console ✨

Optionally, you can add styles to your slides that are only used when the slide shows up in the presenter console:

:css-preview: css/slidepreview.css

And you can style the presenter console itself:

:css-console: css/console.css

There are default styles that are automatic — anything you add in the file for the css-console will just be there to override the existing styling. Iconic behaviour, tbh.

Adding Javascript 🦋

Similar vibe, you can add Javascript files to either header or body:

:js-header: js/firstjsfile.js
:js-body: js/secondjsfile.js

You can also add one extra Javascript-file via a command-line parameter:

hovercraft --js=my_extra.js presentationfile.rst outdir/

Adding Headers and Footers 🌸

If you want static content — content that does not move with each slide — like a header, a footer, your company logo, or a slide background pattern, you can insert that content with the header and footer commands:

.. header::

   .. image:: images/company-logo.png

.. footer::

    "How to use Hovercraft", Yern Busfern, ImaginaryCon 2017

The header will be located in the resulting HTML before the first slide, and the footer will be located after the last slide. But — and this is the important bit — they'll be displayed statically on every slide, and you'll have to position them with CSS yourself. By default the header is displayed behind the slides and the footer is displayed in front of the slides, so the header is useful for background designs and the footer for designs that should be in the foreground. Chef's kiss design logic, honestly.

It genuinely does not matter where in the presentation you add these commands. But I'd recommend adding them before the first slide. 🫶

Styling a specific slide 💖

If you want specific styling for a specifically specific slide, it's a good idea to give that slide a unique ID:

:id: the-slide-id

Then you can style that slide specifically with:

div#the-slide-id {
    /* Custom CSS here */
}

If you don't give it a specific ID, it will get an ID based on its sequence number. And that means the slide's ID will change if you insert or remove slides that came before it — and in that case your custom stylings of that slide will just stop working. 💀 Rude, but that's the deal.

Adding a custom class to slides 🧚

If you want the same style on one or more slides, you may prefer adding a class to those slides instead (or in addition to) a unique ID:

:class: my-custom-class

Then style those slides by adding CSS rules with:

.my-custom-class {
    /* Custom CSS here */
}

Adding a custom directive 👑

If you want to use a [custom docutils directive](http://docutils.sourceforge.net/docs/howto/rst-directives.html), you'll want to run hovercraft in the same process where you register your directive. For example, you can create a custom startup script like the following:

from docutils import nodes
from docutils.parsers.rst import Directive, directives

import hovercraft

class HelloWorld(Directive):
    def run(self):
        para = nodes.paragraph(text='Hello World')
        return [para]

directives.register_directive('hello-world', HelloWorld)

if __name__ == "__main__":
    cmd = ['--skip-help', 'slides.rst']
    hovercraft.main(cmd)

And while creating your own directive might feel mad daunting, it's possible to reuse useful directives from other projects. For example, you can reuse [Pelican's custom code block](http://docs.getpelican.com/en/3.6.3/content.html#syntax-highlighting), which adds an hl_lines option to highlight specific lines of code. To use that directive, just add the following import to the above script:

import pelican.rstdirectives

Portable presentations 🌈

Since Hovercraft! generates HTML5 presentations, you can use any computer that has a modern browser installed to view or show the presentation. This means you can both put the presentation up online and use a borrowed computer for your conference or customer presentation. Travel light, queen.

When you travel you don't know what equipment you'll have to use when you show your presentaton, and it's surprisingly common to encounter a projector that refuses to talk to your computer. It is also very easy to forget your dongle if you have a MacBook, and there have even been cases of computers going completely black and dead when you connect them to a projector, even though all other computers seem to work fine. 😭 not the projector beef

The main way of making sure your presentation is portable is to try it on different browsers and different computers. But the latter can be unfeasible — not everyone has both Windows, Linux and OS X computers at home. To help make your presentations portable it is a good idea to define your own @font-face's and use them, so you're sure that the target browser will use the same fonts as you do. And bestie — Hovercraft! will automatically find @font-face definitions and copy the font files to the target directory. ✨

impress.js fields ⭐

The documentation on impress.js is contained as comments in [the demo html file](https://github.com/bartaz/impress.js/blob/master/index.html). It is not always very clear, so here comes a short summary for convenience.

The different data fields that impress.js will use in 0.5.3, which is the current version, are the following:

  • data-transition-duration: The time it will take to move from one slide to another. Defaults to 1000 (1 second). This is only valid on the presentation as a whole.
  • data-perspective: Controls the "perspective" in the 3d effects. It defaults to 500. Setting it to 0 disables 3D effects.
  • 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-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-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.
  • 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 cool effect, if used right.
  • data-rotate-y: The rotation of a slide in the x-axis, in degrees.
  • 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.

Hovercraft! specialties 🔥

Hovercraft! has some specific ways it uses reStructuredText. First of all, the reStructuredText "transition" is used to mark the separation between different slides or steps. A transition is simply a line with four or more dashes:

----

Okay so plot twist, bestie — you do NOT have to use dashes. You can underline headings with literally any of these characters:

= - ` : . ' " ~ ^ _ * + #

And just like with headings, switching up the character means a different "level". So in theory you can build a whole hierarchical presentation with multiple "levels" of steps. However — and this is the tea — impress.js does not support that at all, so it's only useful if you're making your own templates that use another Javascript library, for example Reveal.js (http://lab.hakim.se/reveal-js/). If you use more than one transition level with the templates that ship with Hovercraft!, the resulting presentation may behave strangely. So like… don't. 🙈

Every reStructuredText field gets converted into an attribute on the current tag. Most of them will typically just be ignored by the HTML rendering, but there are two places where the tags actually make a difference: putting them first in the document, or first on a slide. 👑

Any fields you put first in a document get rendered into attributes on the main impress.js <div>. The only ones Hovercraft! will actually use are data-transition-duration, skip-help, auto-console and slide-numbers.

Any fields you put first in a slide get rendered into attributes on the slide <div>. This is mainly how you set the position/zoom/rotation of the slide — either with data-x, data-y and the other impress.js settings, or the hovercraft-path setting, and we'll get into that later, don't worry.

Hovercraft! starts making the first slide the moment it hits either a transition or a header. Everything before that belongs to the presentation as a whole. So a presentation can look something like this:

:data-transition-duration: 2000
:skip-help: true

.. title: Presentation Title

----

This is the first slide
=======================

Here comes some text.

----

:data-x: 300
:data-y: 2000

This is the second slide
========================

#. Here we have

#. A numbered list

#. It will get correct

#. Numbers automatically

✨ Showing lists item by item ✨

A super common presentation-software feature is a list that shows up one item at a time. That's called "substeps", and you turn it on by setting the substep class on the items you want to reveal. In Hovercraft! the easiest way is to use paragraphs, since you can set the class on multiple paragraphs at once:

.. class:: substep

    This paragraph will be shown when you press <next>

    This will show on the second <next> press

    And this will be shown third

You can also set the class on just individual paragraphs, in which case all the other paragraphs are visible from the start:

This paragraph will always be visible

.. class:: substep

    This paragraph will be shown when you press <next>

And this paragraph will also be always visible

.. class:: substep

    And this paragraph will show second

You can do it with bullet lists or numbered lists too:

.. class:: substep

    * This is an unordered list

        * In two levels

        * One new item will be shown on every <next> press

And, same as with paragraphs, you can control each item individually. But because of the ReStructuredText syntax you can't have individual control over the first item of a list — it will always be shown from the start:

#. This will be shown when you get to this slide

   .. class:: substep

#. The second item shows only after you press <next>

#. This also will always be shown.

   .. class:: substep

#. And this will be shown after another <next> press.

🧮 Mathematical equations

Add a math directive and Hovercraft! will add a link to the MathJax (http://www.mathjax.org/) CDN, so that this:

.. math:: e^{i \pi} + 1 = 0

gets rendered by the MathJax javascript library. 🪄 The math directive also works as a "role", with the equations inlined right into the text flow.

Heads up bestie: if you use the math statement, by default the MathJax library loads from the internet, meaning your presentation needs network connectivity to work. That is a whole problem when you're presenting at conferences, which often have terrible network connectivity. 😭

You can fix this by specifying a local copy of mathjax with the --mathjax command line.

📐 Relative positioning

Hovercraft! lets you position slides relative to each other. You do this by starting the coordinates with "r". This positions the slide 500 pixels to the right and a thousand pixels above the previous slide:

:data-x: r500
:data-y: r-1000

Relative paths let you insert and remove slides and have the other slides adjust automatically. Ngl it's generally the most useful way of positioning. 💅

🎯 Automatic positioning

If you don't specify an attribute, the slide settings are just the same as the previous slide. Which means if you used relative positioning, the next slide moves the same distance.

That gives you a linear movement, and your slides end up in a straight line.

By default the movement is 1600 pixels to the right, so if you don't position any slides at all, you get a standard presentation where the slides simply slide from right to left. 🦋

🌀 SVG Paths

Hovercraft! supports positioning slides along an SVG path. This is so handy — you can make a drawing in any software that supports SVG, then copy-paste that drawing's path straight into your presentation.

You specify the SVG path with the :hovercraft-path: field. For example:

:hovercraft-path: m275,175 v-150 a150,150 0 0,0 -150,150 z

Every following slide that doesn't have any explicit positioning gets placed on this path.

There are some things you need to be careful about when using SVG paths. 👀

🧭 Relative and absolute coordinates

SVG coordinates can be either absolute, referencing the page origin, or relative</>, referencing the last point. Hovercraft! can handle both — what it can not handle very well is a mixture of them.

Specifically: if you take an SVG path that starts with a relative movement and extract that from the SVG document, you lose the context. All coordinates later must then also be relative. If you have an absolute coordinate, you suddenly regain the context, and everything after the first absolute coordinate will be misplaced compared to the points that come before.

Most notable: the open source software "Inkscape" will mix absolute and relative coordinates if you let it use relative coordinates. So you need to go into its settings and uncheck the checkbox that allows relative coordinates. That forces Inkscape to save all coordinates as absolute, which works fine. ✨

🚩 Start position

By default the start position of the path — and therefore the start position of the first slide — is whatever the start position would have been if the slide had no positioning at all. Wanna change it? Just include :data-x: or :data-y: fields. Both relative and absolute positioning work here.

In all cases, the first m or M command of the SVG path is effectively ignored, but you have to include it anyway. Yes, really. 🙃

🔄 SVG transforms

SVG lets you draw up a path and then transform it. Hovercraft! has no support for these transforms, so before you extract the path you should make sure the SVG software isn't using transforms. In Inkscape you do this with the "Simplify" command.

🔺 Other SVG shapes

Hovercraft! doesn't support other SVG shapes — just the path. That's because organising slides in squares, etc, is quite simple anyway, and the shapes can be made into paths. Usually in the software you'll have to select the shape and tell your software to make it into a path. In Inkscape, transforming an object into a path will generally mean the whole path is made of CubicBezier curves, which are unnecessarily complex. Using the "Simplify" command in Inkscape is usually enough to make the shapes into paths.

📏 Shape-scaling

Hovercraft! scales the path so that all the slides that need to fit into the path will fit into the path. So if you have several paths in your presentation, they will not keep their relative sizes — they'll be resized so the slides fit. If you need the shapes to keep their relative sizes, you have to combine them into one path. 💡

🎁 Examples

To see how to use Hovercraft! in practice, there are three example presentations included with Hovercraft!

  • hovercraft.rst (./examples/hovercraft.rst) — The demo presentation you can see at http://regebro.github.com/hovercraft
  • tutorial.rst (./examples/tutorial.rst) — A step by step guide to the features of Hovercraft!
  • positions.rst (./examples/positions.rst) — An explanation of how to use the positioning features.

🎨 DESIGNING YOUR PRESENTATIONS 🎨

okay so bestie, here's the tea on making presentations actually hit 💅 I'm not claiming to be an expert, like at all, but here are some beginner hints, no cap.

✨ Take it easy ✨

do not go feral with the zoom, bestie. If two slides have a scale difference of more than 5, it's rarely gonna look good. Like, yeah, it would be a cute cool zooming effect if it did work that way — but browsers are simply not designed for that, so it won't. periodt. 💀

and the 3D effects?? iconic when used well. really cool. but not all the time — it gets tiring for your audience and they'll start checking their phones. 🙈

try, if you can, to use the zoom and 3D effects when they actually make sense in the presentation. example: you can mention the main topics on one slide, and then zoom in on each topic when you discuss it in more detail. that way the effects help clarify the presentation instead of distracting from it. main character energy for your slides fr fr.

🎀 Custom fonts 🎀

browsers render things subtly differently. like, they just do.

they also have different default fonts, and different operating systems have different implementations of the same fonts. so to make sure you have as much control over the design as possible, you should always include fonts with the presentation. a good source for free fonts is Google Webfonts http://www.google.com/webfonts. those fonts are free and open source, so you can use them with no cost and no risk of being sued 🫶 they can also be downloaded or included online.

🦋 Online vs Downloaded 🦋

if you're making a presentation that's gonna run on your computer at a conference or a customer meeting — always download the fonts and have them as part of the presentation. put them in a folder called fonts under the folder where your presentation is. simple as that.

you also need to define the font-family in your CSS. Font Squirrel http://www.fontsquirrel.com/'s webfont generator will hook you up with a platform-independent toolkit for generating both the varius font formats and the CSS. (that's their spelling, not mine, iykyk 💖)

if the presentation is online only, you can put an @include-statement in your CSS to include Google's webfonts directly:

@import url(http://fonts.googleapis.com/css?family=Libre+Baskerville|Racing+Sans+One|Satisfy);

but don't use this for things you need to show on your computer, because it requires you to have internet access. imagine the wifi dies mid-presentation... not the vibe 🙈

🌸 Test with different browsers 🌸

if you're putting the presentation online, test it with a couple of major browsers to make sure nothing breaks and that everything still looks good. not only are there subtle differences in how things may get positioned — different browsers are also good at different things. it's giving ✨chaos✨ but we deal.

I've tested some browsers, all on Ubuntu, and it's likely that they behave differently on other operating systems, so you have to try for yourself, bestie. 💜

🔥 Firefox

Firefox 18 is quite slow to use with impress.js, especially for 3D stuff, so it can have very jerky movements from slide to slide. on the bright side, it does keep text looking good no matter how much you zoom. on the other hand, it refuses to scale text infinitely, so if you scale too much, characters will not grow larger — they'll instead start moving around. 💀

Firefox 19 is better, but for 3D stuff it's still a bit slow.

🔥 Chrome

Chrome 24 is fast, but will not redraw text in different sizes. instead it creates an image of the text and rescales it, resulting in the previous slide having a fuzzy pixelated effect. 😭

🔥 Epiphany

Epiphany 3.4.1 is comparable to Firefox 19, possibly a bit smoother, and the text looks good. but it has bugs in how it handles 3D data, and the location bar is visible in fullscreen mode, making it less suitable for any sort of presentation. 🚩

🧚 TEMPLATES 🧚

good news bestie: for most cases you don't need to create your own template, because the default template is very simple and most things you need to do are doable with css. slay.

however — I don't want Hovercraft! to set up a wall where it isn't flexible enough for your needs, so I added support for making your own templates. 🫶

you need to create your own template if you're unsatisfied with the HTML that Hovercraft! generates. for example, if you need to use another version of HTML, or if the reStructuredText you're using isn't being rendered in a way that's useful for you. although — if you aren't happy with the HTML generated from the reStructuredText, that could very well be a bug, so open an issue on Github https://github.com/regebro/hovercraft for discussion. 👑

Hovercraft! generates presentations by converting the reStructuredText into XML and then using XSLT to translate the XML into HTML.

Templates are directories with a configuration file, a template XSL file, and any number of CSS, JS and other resource files.

⭐ The template configuration file ⭐

the configuration file is normally called template.cfg, but if you have several configuration files in one template directory, you can specify which one to use by specifying the full path to the configuration file. however, if you just specify the template directory, template.cfg will be used.

template files are in configparser format, which is an extended ini-style format. they're very simple and have only one section, [hovercraft]. any other sections will be ignored. (rude, but okay.) many of the parameters are lists that often don't fit on one line — in that case you can split the line up over several lines, but indent the lines. the amount of indentation doesn't make any difference, except aesthetically. ✨

the parameters in the [hovercraft] section are:

  • template — the name of the xsl template.
  • css — a list of CSS filenames separated by whitespace. these files will get included in the final file with "all" as the media specification.
  • css-<media> — a list of CSS filenames separated by whitespace. these files will get included in the final file with the media given in the parameter. so the files listed for the parameter css-print will get "print" as their media specification, and a key like css-screen,print will return media "screen,print".
  • js-header — a list of filenames separated by whitespace. these files will get included in the target file as header script links.
  • js-body — a list of filenames separated by whitespace. these files will get included in the target file as script links at the end of the file. the files impress.js, impressConsole.js and hovercraft.js typically need to be included here.
  • resources — a list of filenames separated by whitespace that will be copied to the target directory, but nothing else is done with them. images and fonts used by CSS will be copied anyway, but other resources may be added here.
  • resource-directories — a list of directory names separated by whitespace. these will be treated like resources above, ie only copied to the target directory. the directory contents will be copied recursively, but hidden files (like files starting with a .) are ignored.

an example:

[hovercraft]
template = template.xsl

css = css/screen.css

css-print = css/print.css

js-header = js/dateinput.js

js-body = js/impress.js
          js/hovercraft.js

resources = images/back.png
            images/forward.png
            images/up.png
            images/down.png

💜 The template file 💜

the file specified with the template parameter is the actual XSLT template that will perform the translation from XML to HTML.

most of the time you can just copy the default template file in hovercraft/templates/default/template.xsl and modify it. XSLT is very complex, but modifying the template's HTML is quite straightforward, as long as you don't have to touch any of the <xsl:...> tags. 🙏

also, the HTML that is generated is XHTML compatible and quite straightforward, so for the most part all you'd need to do to generate another version of HTML — for example strict XHTML — would be to change the doctype.

but if you need to add or change the main generated HTML, you can add and change HTML statements in this main file as you like. see for example how the little help-popup is added to the bottom of the HTML.

if you want to change the way the reStructuredText is rendered, things get slightly more complex. the XSLT rules that convert the reStructuredText XML into HTML are contained in a separate file, reST.xsl. for the most part you can just include it in the template file with the following code:

<xsl:import href="resource:templates/reST.xsl" />

the resource: part here is not a part of XSLT, but a part of Hovercraft! it tells the XSLT translation that the file specified should not be looked up on the file system, but as a Python package resource. currently the templates/reST.xsl file is the only XSLT resource import available.

if you need to change the way reStructuredText is rendered, you need to make a copy of that file and modify it. you then need to make a copy of the main template and change the reference in it to your modified XSLT file.

⚠️ none of the XSLT files need to be copied to the target, and they should not be listed as a resource in the template configuration file. don't do it bestie, I'm begging 🥺

👑 Author 👑

Lennart Regebro

2013-2019, Lennart Regebro

aaaand that's the whole page, bestie!! 🎀✨ this was HOVERCRAFT(1), version 2.7, dated 2026-01-02 — go forth and make something iconic, you've absolutely got this 💅💖🦋

📦 where this page comes from