Permalink
Fetching contributors…
Cannot retrieve contributors at this time
190 lines (127 sloc) 4.78 KB

Styling Slides

Styling

  • Slides are contained in <article> elements
  • Each slide has an HTML id that corresponds to the permalink ID generated by Sphinx (for example, you're currentling reading styling).
  • The heading level is added as a class; ie, level-2
  • Slides may be styled using a theme, or custom CSS.
  • You can enable :confval:`slide numbers <slide_numbers>` or a :confval:`slide footer <slide_footer>` with configuration settings.

Included Themes

Hieroglyph includes three :ref:`themes <custom-themes>`.

slides

Two slides levels: the first level of headers become "section" headers, and the second become the real content.

single-level

Based on the default slides theme. Only one style of slide, every slide has a title at the top.

slides2

Based on the updated (2012+) Google I/O HTML slides template. This theme is new in 0.7.

Setting the Theme

You can set your theme using the slide_theme configuration setting.

slide_theme = 'single-level'

If you're using a custom theme, you can also set the directory to look in for themes:

slide_theme_path = '...'

Incremental slides (builds)

.. slide:: Incremental Slides
   :level: 2

   .. rst-class:: build

   - Adding the ``build`` class to a container
   - To incrementally show its contents
   - Remember that *Sphinx* maps the basic ``class`` directive to
     ``rst-class``. For example::

       .. rst-class:: build

       - Bullet 1
       - Bullet 2


It's common to have a slide with a list of items that are shown one at a time. Hieroglpyh supports this through the use of the build class. Let's add a third slide to index.rst that incrementally displays a bulleted list.

Show Bullets Incrementally
==========================

.. rst-class:: build

- Adding the ``build`` class to a container
- To incrementally show its contents
- Remember that *Sphinx* maps the basic ``class`` directive to
  ``rst-class``

Here the :rst:dir:`rst-class` directive causes the next element to be built incrementally.

Setting a Class on Slides

You can set the CSS class on a slide using the normal :rst:dir:`rst-class` directive. (Sphinx remaps class to :rst:dir:`rst-class` to avoid conflicts.) For example:

.. rst-class:: myclass

Slide Heading
-------------

The :rst:dir:`rst-class` directive applies to the next following element (the heading Slide Heading in this example).

You can also set a default class on slides using the slide_classes option of the :rst:dir:`slideconf` directive. Note that specifying an explicit class will override the slide_classes.

Slide Classes

Hieroglyph includes some pre-defined style classes.

title-image

Designed to be used as a title slide with a full screen image. Use the figure directive to specifiy the image and caption.

Custom CSS

The standard Hieroglyph themes support adding a custom stylesheet with the slide_theme_options dict in conf.py:

slide_theme_options = {'custom_css': 'custom.css'}

The custom CSS file should be located in the html_static_path (_static by default).

Slide Transitions

Most themes use a default transition between slides. For the slides and slides2 theme, the next slide moves in from the right, sliding on top of the previous one. This isn't always desirable: sometimes you want to skip the transition so that you can do more interesting "builds" using multiple slides.

The slide transitions are implemented using CSS transitions. The slides2 CSS includes the following declaration:

slides > slide {
  -webkit-transition: all 0.6s ease-in-out;
  -moz-transition: all 0.6s ease-in-out;
  -o-transition: all 0.6s ease-in-out;
  transition: all 0.6s ease-in-out;
}

This tells the browser to take 0.6s to transition between slides.

If you want to omit the transition altogether, you can add :ref:`custom-css` to override this.

slides > slide {
  -webkit-transition: none;
  -moz-transition: none;
  -o-transition: none;
  transition: none;
}

If you only want to selectively change the transition timing, you can define a class and :ref:`set a class on the slide<setting-slide-class>`.

Adding Javascript

In addition to a custom CSS file, it is sometimes useful to include some custom Javascript for your slides. You can put this in your static directory (_static by default), and then reference it in the slide_theme_options dict in conf.py:

slide_theme_options = {'custom_js': 'myslides.js'}