Hieroglyph themes are based on Sphinx's HTML themes. Themes are
either a directory or zipfile, and consist of a
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:
Create a directory for your theme.
This directory will need to be somewhere Sphinx and Hieroglyph can find it. You can set the 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.
theme.confdefines your theme's options and what theme it's based on. Good choices are
basic(bare-bones Sphinx theme),
The Sphinx documentation describes what goes into theme.conf.
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
slide.htmltemplate is rendered for each individual slide.
Specify additional pages to generate in the
When defining a slide theme, inherit from the
slides theme for
basic support. For example, the
single-level them has the
[theme] inherit = slides stylesheet = single.css [options] custom_css =
In order to include the base slide styling, your theme's stylesheet should begin with:
slides.css will be supplied by the base theme (
layout.html template defines the container for your
as any markup needed for the presentation.
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 template is rendered for each individual slide. The
following variables are available for your templates:
- The HTML ID for this slide. This is generated by Sphinx from the title content.
- The slide title. This may contain nested HTML if the slide title includes inline markup.
- The slide heading level.
- HTML content for the slide.
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
slides2theme uses this for setting classes on the inner
- A list of remaining classes; ie, those without the
- A list of all classes assigned to the slide, regardless of prefix.
No prefixes are stripped in
- The slide number for the current slide.
- A reference to the Sphinx Configuration.
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.