Hieroglyph is an extension for Sphinx which builds HTML slides from ReStructured Text documents.

This document provides a basic overview of Hieroglyph; dive deeper with the following documents:


  • You’re already writing documentation using Sphinx
  • You want to keep your presentation content in sync with other documentation
  • You want slides that look beautiful
  • Why Not?

Using Hieroglyph§

Install from PyPI (or github):

pip install hieroglyph

Add Hieroglyph as a Sphinx extension to your configuration:

extensions = [

Build your slides:

$ sphinx-build -b slides output/slides

Adding Hieroglyph to your Makefile§

You make optionally want to add the following to your Makefile:

        $(SPHINXBUILD) -b slides $(ALLSPHINXOPTS) $(BUILDDIR)/slides
        @echo "Build finished. The HTML slides are in $(BUILDDIR)/slides."

The directory builder is analogous to Sphinx’s HTML Directory builder . Each document is placed in its own directory as index.html, which allows you to omit the file from the URL.

You can add this to the Makefile with the following:

        $(SPHINXBUILD) -b dirslides $(ALLSPHINXOPTS) $(BUILDDIR)/slides
        @echo "Build finished. The HTML slides are in $(BUILDDIR)/slides."

(Don’t forget, Makefiles love tabs!)

You can also include your slides inline with HTML. See Hieroglyph Builders for details.

Writing Your Document§

  • First and second level headings become slides
  • Default theme styles these differently for topic breaks
  • Otherwise it’s just ReStructured Text!

Incremental Slides§

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

Slide-Only (and non-slide) Content§

Two directives let you restrict whether content is included:

.. ifslides::

.. ifnotslides::


These directives were originally named slides and notslides, respectively. They were renamed prior to the addition of the slide directive, to be more explicit.

The old names work, but will show a warning during the build process. Expect the old names to be removed in some future version.

Styling Slides§

  • Slides are just HTML, so you can write CSS to style them, either individually or as a whole

  • You can add a custom CSS file to most themes by adding a custom_css theme options:

    slide_theme_options = {'custom_css':'custom.css'}
  • Custom CSS files are contained in your documentation’s static files directory (usually _static)


Hieroglyph includes two themes:


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


Only one style of slide, every slide has a title at the top.

See Styling Slides for more information on using themes and writing your own.


Hieroglyph has some configuration dials you can turn to customize the output. In addition to the theme, you can configure:

  • The number of heading levels which become slides
  • Linking between slides and HTML documentation

See Hieroglyph Configuration for more information.

Presenter Console§

Hieroglyph includes a simple presenter console to make it easier to use when presenting slides.

To activate the console, press “c” when viewing the slides.

The console will open in a new window. Advancing the slides in either window will update the other one, as well.


Hieroglyph is made available under a BSD license; see LICENSE for details.

Included slide CSS and JavaScript originally based on HTML 5 Slides licensed under the Apache Public License.