Themes#

Sigal themes are created using the Jinja2 templating system.

Bundled themes#

Sigal comes with three themes, located in the sigal/themes folder:

colorbox:: source, demo. This theme uses a Swipe plugin to browse pictures on touch devices.
galleria:: source, demo. This theme is based on the classic theme, pictures can be browsed with left/right keys, fullscreen support is available with the f key, and a map can be shown with the m key if the show_map setting is True. The leaflet_provider setting can be used to customize the tile provider (using Leaflet-providers).
photoswipe:: source, demo.

The themes folder also includes a default theme. This theme cannot be used on its own, instead, it contains Jinja2 templates that are used by the bundled themes to enable functionality such as the feeds and ZIP gallery plugins, as well as settings such as Google Analytics.

Creating a theme#

Sigal requires the following two templates in order to generate a gallery. These templates must be located in THEME_DIR/templates:

album_list.html: Generates the album list, if you have multiple albums
album.html: Generates each individual album page

Themes may also include static content such as CSS and JavaScript by placing this content in the THEME_DIR/static folder. You can then access this content in your template by using the theme.url variable.

Custom themes may also include the templates available in the default theme.

Variables#

You can use the following variables in your template:

album: The current album that is rendered in the HTML file, represented by an Album object. album.medias contains the list of all medias in the album (represented by the Image and Video objects, inherited from Media).
index_title: Name of the index. This is either the directory name or the title specified in the index.md of the source directory.
settings: The entire dictionary from sigal.conf.py.
sigal_link: URL to the Sigal homepage.
theme.name, theme.url: Name and url of the currently used theme.

Filters#

You can define custom jinja filters for your template by creating a filters.py script at the root of your template directory.

This script will then be imported and all defined functions will be available as jinja filters with the same names in your templates.

Documentation of sigal’s main classes#

class sigal.gallery.Album(path, settings, dirnames, filenames, gallery)#

Gather all informations on an album.

Attributes:

Variables:

description_file – Name of the Markdown file which gives information on an album
index_url – URL to the index page.
output_file – Name of the output HTML file
meta – Meta data from the Markdown file.
description – description from the Markdown file.

For details how to annotate your albums with meta data, see Album information.

property albums#: List of Album objects for each sub-directory.

property author#: Author extracted from the Markdown index.md file or settings.

property breadcrumb#: List of (url, title) tuples defining the current breadcrumb path.

create_output_directories()#: Create output directories for thumbnails and original images.

property description#: Description extracted from the Markdown index.md file.

description_file = 'index.md'#

property images#: List of images (Image).

property markdown_metadata#: Get metadata from filename.md: title, description, meta.

property markdown_metadata_filepath#

property meta#: Other metadata extracted from the Markdown index.md file.

property nbmedias#

property random_thumbnail#

property show_map#: Check if we have at least one photo with GPS location in the album

sort_medias(medias_sort_attr)#

sort_subdirs(albums_sort_attr)#

property thumbnail#: Path to the thumbnail of the album.

property title#: Title extracted from the Markdown index.md file.

property url#: URL of the album, relative to its parent.

property videos#: List of videos (Video).

property zip#: Placeholder ZIP method. The ZIP logic is controlled by the zip_gallery plugin

class sigal.gallery.Media(filename, path, settings)#

Base Class for media files.

Attributes:

Variables:

Media.type – "image" or "video".
Media.dst_filename – Filename of the resized image.
Media.thumbnail – Location of the corresponding thumbnail image.
Media.big – If not None, location of the unmodified image.
Media.big_url – If not None, url of the unmodified image.

property big#: Path to the original image, if keep_orig is set (relative to the album directory). Copy the file if needed.

property big_url#: URL of the original media.

property description#: Description extracted from the Markdown <imagename>.md file.

dst_filename#: Filename of the resized image.

property dst_path#

property file_metadata#: Type-specific metadata

property markdown_metadata#: Get metadata from filename.md: title, description, meta.

property markdown_metadata_filepath#

property meta#: Other metadata extracted from the Markdown <imagename>.md file.

src_ext#: Input extension.

src_filename#: Filename of the input image.

property thumb_path#

property thumbnail#: Path to the thumbnail image (relative to the album directory).

property title#: Title extracted from the metadata, or defaults to the filename.

type = ''#: Type of media, e.g. "image" or "video".

property url#: URL of the media.

class sigal.gallery.Image(filename, path, settings)#

Gather all informations on an image file.

property big#: Path to the original image, if keep_orig is set (relative to the album directory). Copy the file if needed.

property big_url#: URL of the original media.

property date#: The date from the EXIF DateTimeOriginal metadata if available, or from the file date.

property description#: Description extracted from the Markdown <imagename>.md file.

dst_filename#: Filename of the resized image.

property dst_path#

property exif#: If not None contains a dict with the most common tags. For more information, see Simpler EXIF data output.

property file_metadata#: Image file metadata (Exif and IPTC)

has_location()#: True if location information is available for EXIF GPSInfo.

property input_size#: The dimensions of the input image.

property markdown_metadata#: Get metadata from filename.md: title, description, meta.

property markdown_metadata_filepath#

property meta#: Other metadata extracted from the Markdown <imagename>.md file.

property raw_exif#: If not None, contains the raw EXIF tags.

property size#: The dimensions of the resized image.

src_ext#: Input extension.

src_filename#: Filename of the input image.

property thumb_path#

property thumb_size#: The dimensions of the thumbnail image.

property thumbnail#: Path to the thumbnail image (relative to the album directory).

property title#: Title extracted from the metadata, or defaults to the filename.

type = 'image'#: Type of media, e.g. "image" or "video".

property url#: URL of the media.

class sigal.gallery.Video(filename, path, settings)#

Gather all informations on a video file.

property big#: Path to the original image, if keep_orig is set (relative to the album directory). Copy the file if needed.

property big_url#: URL of the original media.

property date#: The date from the Date metadata if available, or from the file date.

property description#: Description extracted from the Markdown <imagename>.md file.

dst_filename#: Filename of the resized image.

property dst_path#

property file_metadata#: Type-specific metadata

property markdown_metadata#: Get metadata from filename.md: title, description, meta.

property markdown_metadata_filepath#

property meta#: Other metadata extracted from the Markdown <imagename>.md file.

src_ext#: Input extension.

src_filename#: Filename of the input image.

property thumb_path#

property thumbnail#: Path to the thumbnail image (relative to the album directory).

property title#: Title extracted from the metadata, or defaults to the filename.

type = 'video'#: Type of media, e.g. "image" or "video".

property url#: URL of the media.

Simpler EXIF data output#

Because the tags in the media.raw_exif dictionary are a little bit cumbersome to use, some common tags are extracted and formatted for easy use in templates. If available, you can use:

media.exif.iso

The ISO speed rating.

media.exif.focal

The focal length, formatted as a decimal number.

media.exif.exposure

The exposure time formatted as a fractional number, e.g. “1/500”.

media.exif.fstop

The aperture value given as an F-number and formatted as a decimal.

media.exif.datetime

The time the image was taken. It is formatted with the datetime_format setting, which is %c by default. See Python’s datetime documentation for a list of all possible values.

media.exif.dateobj

The time the image was taken. It is a datetime object, that can be formatted with strftime:

{% if media.exif.dateobj %}
    {{ media.exif.dateobj.strftime('%A, %d. %B %Y') }}
{% endif %}

This will output something like “Monday, 25. June 2013”, depending on your locale.

media.exif.gps

If not None, the dict contains two keys lat and lon denoting the GPS coordinates of the location where the image was taken. lat will always be referenced to the north pole whereas lon will be referenced to east to the prime meridan. To provide a link on an OpenStreetMap you could write a template like this:

{% if media.exif.gps %}
    <a href="https://www.openstreetmap.org/?mlat={{
        media.exif.gps.lat }}&mlon={{
        media.exif.gps.lon }}#map=18/{{
        media.exif.gps.lat }}/{{
        media.exif.gps.lon }}">Go to location (OpenStreetMap)</a>
{% endif %}