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:
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.
Create a
theme.conf
theme.conf
defines your theme’s options and what theme it’s based on. Good choices arebasic
(bare-bones Sphinx theme),slides
, orslides2
(Hieroglyph themes).The Sphinx documentation describes what goes into theme.conf.
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 abody
block.Create a
slide.html
file.The
slide.html
template is rendered for each individual slide.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 innerarticle
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.