Gallery macro

Back to Available macros

The Gallery macro generates an image gallery. The supported image formats are PNG, JPEG, GIF, SVG, and SVGZ. These image formats are the ones that are well-supported in browsers (as of October 2012). Thumbnails are automatically generated for images with filename extensions .png, .gif, .jpeg, .jpg. The Gallery macro uses the Pillow library to generate the thumbnails. If the Pillow library is not installed, then the Gallery macro will still run, but thumbnails will not be generated (a warning is given in this case).

Properties

Output expansion default

Disabled.

Parameters

A list of the following form:

image1.png
- Caption for the first image.
- More caption for the first image.
image2.jpg
- Caption for the second image.
image4.gif
image5.svg
...

Specification of captions is not required.

Variables

Gallery.thumbnail_max_width
A maximum for the width of a thumbnail in pixels. Default 300.
Gallery.thumbnail_max_height
A maximum for the height of a thumbnail in pixels. Default 300.

The pixel-count defines the resolution of the thumbnail image for the pixel-based images; if the number of pixels is too low compared to the presentation size (defined by the CSS), the thumbnail image will look blurry.

Multiple image formats

If an image file has multiple formats in the same directory, say lookaheads.png and lookaheads.svg, then they are assumed to be the same image in different formats. If there is an image file for which thumbnails can be generated, then that image file is used to generate the thumbnail. In particular, this covers for the fact that, as of October 2012, there aren’t any good open-source libraries for converting SVG to a pixel-based image.

Width and height of thumbnails

To set the maximum allowed presentation width and height for the image thumbnails, modify the max-width and max-height properties of the .highslide img selector in highslide.css. The defaults for these are 45% and 20% (of the containing element), respectively.

Thumbnail naming

The thumbnails will be stored at the remark_files/thumbnails directory of the output root-directory. A thumbnail is named such that it starts with the image filename without the extension, and is then followed by (a dash - and) a hash of the relative-path in hex-form which disambiguates images with equal filenames.

Using hashing for disambiguation means that images with equal filenames may sometimes collide (they will then have the same thumbnail image). The probability of this happening is governed by the birthday paradox. Given the current implementation, which uses a 64-bit hash, over 6 million files with equal filenames need to be generated to get a collision with a one-in-a-million probability.

Warnings

vector-thumbnail
This warning is generated when an SVG file is used as its own thumbnail. Depending on the complexity of the SVG file this might cut out unnecessary amount of performance from the browsing of the webpage. To fix this, provide a pixel-based alternative image to create the thumbnail from.
thumbnail-failed
This warning is generated when the creation of a thumbnail fails for a reason or another.

Example

[[Gallery]]:
    hsv.png
    - A visualization of the HSV color space (with full saturation).
    - This text is appended to the caption.
    lookaheads.svg
    - Lookahead-sets in LC(1)-parsing

See also

File searching algorithm

Files

Gallery macro

Generates an image gallery with thumbnails.