This article continues the documentation of the Photo Gallery configuration documented in the article Creating a Photo Gallery Article.

While getting started with a default photo gallery is relatively easy (one configuration variable and a metadata field per article), enabling some of the more advanced features requires a little more effort. This effort will allow for the inclusion of single gallery photos into articles and the fine tuning of the image transformations used to render the photos for the photo galleries and articles. Together these changes will give you the power to customize your photo gallery to your requirements.

Prior to including single gallery photos in articles, the PHOTO_LIBRARY configuration variable must first be set to the full path of the directory containing all of the galleries. For example, in the previous article, Creating a Photo Gallery Article, the gallery was added to the article as follows:

gallery: {filename}../gallery-source/dragondance

Assuming that you have installed a standard installation of Pelican in the directory /home/stuff/blog-content and inferring from the above metadata that all photo galleries are located in the content/gallery-source directory, the full path to the galleries should be as follows:

PHOTO_LIBRARY = '/home/stuff/blog-content/website/content/gallery-source'

Adding a Single Photos to an Article

Once the above configuration has been completed, add a photo into the body of an article using the following format: {photo}folder/image.jpg. The {photo} part of the format calls out this image as part of a gallery, and instructs the Photos plugin to resize a photo specifically for use in articles. The folder part refers to the folder representing the gallery, and the image.jpg is the filename of the photo within the folder directory.

For example, say you want to highlight one of the photos, photo-1.jpg, that was contained within the dragondance gallery presented in your article. To include it in a Markdown article, add the following text to the article:

![first image]({photo}dragondance/photo-1.jpg)

In addition, using the prefix {lightbox} instead of {photo} will cause the thumbnail of the photo to be displayed in the article. Clicking on the thumbnail will bring up the full sized image from the photo gallery, similar to how it was displayed in the photo gallery.

Modifying Image Display in Galleries

There is a small amount of configuration that is available to modify how a single photo is displayed in the galleries. These modifications include specifying captions for one or more photos, specifying EXIF information for one or more photos, and specifying one or more photos to not display as part of the gallery.

All three of these modifications are controlled by text files that are located in the same source directory as the photos. These text files provide extra information that is used when the article containing the specified photo gallery is being generated.

For the first two choices, there are two distinct files: exif.txt and captions.txt. In both cases, the file format is simply the name of the image, a colon, and the information to associate with the photo.

For example, the information in the exif.txt may be:

best.jpg: Canon EOS 5D Mark II - 20mm f/8 1/250s ISO 100

and the information in the captions.txt file may be:

best.jpg: My best photo ever! How lucky of me!

Elegant will display both of these pieces of information at the bottom of the popup for an individual image.

To remove keep the photo file in a gallery, but not show it as part of the gallery, the blacklist.txt file is used. Even simpler than the previous two files, the file format is simply the name of the photo to exclude, one photo to a line.

For example, to keep the file this-file-will-be-skipped.jpg in the gallery directory but not display it as part of the gallery, the blacklist.txt file would look like this:


Caching Processed Images

To reduce the need to reprocess images to fit into the gallery, article, and thumbnail sizes, the Photo plugin only processes images if the output file is not already present in the destination directory. As such, to apply any configuration changes to images that have already been processed, their destination images need to deleted from the relevant directories under the photos directory from the Pelican output.

As both of the following sections change configuration variables that affect how the images are processed, this note on caching applies to any changes of configuration variables specified in the following sections.

Advanced Configuration Values

The definitive list of the values and their defaults is located on the Photos Plugins webpage.

The definitive list has been pared down, tested, and documented with specific focus on the Elegant theme. Testing was performed using the list from the Photos Plugin webpage along with the source code for the Photos Plugin. Any significant difference between the behavior documented below and the definitive list is usually attributed to differences between the source code and the documentation for the Photos Plugin.

As a decent part of this information is presented after testing and research, please feel free to contact us if you see different behavior than is documented here.

Configuration Name Default Value Description
PHOTO_GALLERY (1024, 768, 80) Three attributes, describing the maximum width, the maximum height, and the quality of the resized image. The specific set of attributes applies to the maximum size of the photo displayed when the reader clicks on a gallery’s thumbnail image in the article. Note that the quality of the resized image only applies to JPG images.
PHOTO_ARTICLE (760, 506, 80) The same attributes as PHOTO_GALLERY, but for the size of a photo from a gallery used in an article.
PHOTO_THUMB (192, 144, 60) The same attributes as PHOTO_GALLERY, but for the size of the thumbnails used to show the contents of the gallery.
PHOTO_SQUARE_THUMB False This setting controls whether or not the thumbnails retain their aspect ratio when resized. If this setting is True, the thumbnails will not retain their aspect ratio and will be cropped to fit into the rectangle defined by the PHOTO_THUMB configuration variable.
PHOTO_RESIZE_JOBS 1 Number of resize jobs to be run in parallel. If installed on a Windows machine, read this.
PHOTO_WATERMARK True Add a watermark to all photos in articles and pages. The watermarks added are controlled by the PHOTO_WATERMARK_TEXT and PHOTO_WATERMARK_IMG configuration variables described below. Note that if both are specified, both will be used.
PHOTO_WATERMARK_TEXT SITENAME Text to use for the watermark.
PHOTO_WATERMARK_TEXT_COLOR (255, 255, 255) Color of the text used for the watermark.
PHOTO_WATERMARK_IMG '' Full path to the image to use as a watermark.
PHOTO_WATERMARK_IMG_SIZE False Size to apply to the watermark image, expressed as (width,height).

JPG Specific EXIF Configuration Values


The photos plugin requires the Python piexif package to provide control over any EXIF information in the images.

Configuration Name Default Value Description
PHOTO_EXIF_KEEP False Keep the EXIF information from the input photo.
PHOTO_EXIF_REMOVE_GPS False Remove any EXIF GPS information from the photos.
PHOTO_EXIF_AUTOROTATE True Use the EXIF orientation field to determine how to rotate the photo so all photos are in a standard orientation.
PHOTO_EXIF_COPYRIGHT False If not False and no existing copyright information is provided in the image, attach an author and license to the file. Choices include: - COPYRIGHT, CC0, CC-BY-NC-ND, CC-BY-NC-SA, CC-BY, CC-BY-SA, CC-BY-NC, CC-BY-ND
PHOTO_EXIF_COPYRIGHT_AUTHOR SITENAME If PHOTO_EXIF_COPYRIGHT is not False and no copyright author is present in the image, use this value as the author.

Like this post? Share on: TwitterFacebookEmail

Talha Mansoor Avatar Talha Mansoor is the creator and lead developer of Elegant theme.
Jack De Winter ever evolving, ever learning

Keep Reading


Last Updated


Supported Plugins


Stay in Touch

Get New Release Alert