Creating Themes

Hieroglyph themes are based on Sphinx’s HTML themes. Themes are either a directory or zipfile, and consist of a theme.conf file, templates you wish to override, and a static/ directory which contains images, CSS, and other static assets.

To create a new theme, follow these steps:

  1. Create a directory for your theme.

    This directory will need to be somewhere Sphinx and Hieroglyph can find it. You can set the slide_theme_path (in analogy to html_theme_path) in your project to the path, if needed. If you plan to distribute your theme, simply add the sphinx_themes entry point.

  2. Create a theme.conf

    theme.conf defines your theme’s options and what theme it’s based on. Good choices are basic (bare-bones Sphinx theme), slides, or slides2 (Hieroglyph themes).

    The Sphinx documentation describes what goes into theme.conf.

  3. Create layout.html, if needed.

    If your theme needs any custom HTML around the slides content, override layout.html. At the minimum, this template must define a body block.

  4. Create a slide.html file.

    The slide.html template is rendered for each individual slide.

  5. Specify additional pages to generate in the theme.conf

theme.conf

When defining a slide theme, inherit from the slides theme for basic support. For example, the single-level them has the following theme.conf:

[theme]
inherit = slides
stylesheet = single.css

[options]
custom_css =

In order to include the base slide styling, your theme’s stylesheet should begin with:

@import url(slides.css);

slides.css will be supplied by the base theme (slides).

layout.html

The layout.html template defines the container for your presentation. This includes links to CSS and Javascript files, as well as any markup needed for the presentation.

Sphinx (and therefore Hieroglyph) uses Jinja for templating. The Sphinx templating documentation has general information and a list of available helper functions.

When creating links in layout.html (and other templates), it’s important to use the pathto function. The pathto function will ensure the link is generated with the correct path when the presentation is built.

slide.html

The slide.html template is rendered for each individual slide. The following variables are available for your templates:

id

The HTML ID for this slide. This is generated by Sphinx from the title content.

title

The slide title. This may contain nested HTML if the slide title includes inline markup.

level

The slide heading level.

content

HTML content for the slide.

content_classes

A list of all classes that had the content- prefix. The prefix is stripped in the list.

This may be useful if your markup requires classes for elements that don’t directly map to RST constructs. For example, the slides2 theme uses this for setting classes on the inner article HTML element.

slide_classes

A list of remaining classes; ie, those without the content- prefix.

classes

A list of all classes assigned to the slide, regardless of prefix. No prefixes are stripped in classes.

slide_number

The slide number for the current slide.

config

A reference to the Sphinx Configuration.

Additional Pages

Hieroglyph also allows specification of extra pages to build in the theme configuration. Any key in options that begins with extra_pages_ specifies an additional page to be built. The base slides theme specifies the console in this manner:

[options]
custom_css =
custom_js =
extra_pages_console = console.html

The value of the key (console.html in this case) specifies the template to use to render the page.