Enhance Your Pelican Website with Image Preview Thumbnails

March 10, 2024

If you’re looking to add a touch of visual appeal to your Pelican website, the Image Preview Thumbnailer plugin is here to help. This Pelican plugin allows you to insert thumbnails along image links, providing an enticing preview for your visitors. In this article, we’ll explore how you can leverage this plugin to level up your Pelican website.

Installation and Setup

To get started with the Image Preview Thumbnailer plugin, follow these simple steps:

Install the package from PyPI using the command: pip install pelican-plugin-image-preview-thumbnailer
Add the plugin to your pelicanconf.py file by including 'image_preview_thumbnailer' in the PLUGINS list.
Enable the plugin on the articles or pages you wish to add image preview thumbnails to by inserting the following metadata:
```
#yaml
   Image-preview-thumbnailer: $selector
   
```
The $selector is a CSS selector that targets the HTML elements the plugin will parse and look for <a> hyperlinks. You can provide multiple comma-separated values as CSS selectors to the Image-preview-thumbnailer metadata field.

Supported Link Formats

The Image Preview Thumbnailer plugin currently supports preview of the following link formats:

“raw” links to GIF/JPEG/PNG images
links to Wikipedia/Wikimedia images
links to ArtStation artwork pages
links to Behance artwork pages
links to Dafont font pages
links to FreeSVG.org vector images
links to Pixabay images
links to pages with a <meta property="og:image"> or <meta property="twitter:image"> properties, such as DeviantArt artworks, Flickr photos, itch.io pages, OpenGameArt assets, or WikiArt pages

If you have more image hosting websites you would like to see supported, feel free to submit a pull request and add support for them!

Displaying Thumbnails on Hover

The Image Preview Thumbnailer plugin was initially designed to add “🖼️” icons after image links and only display thumbnails when hovering over those icons. To configure the plugin to behave this way, follow these steps:

Define the following line in your pelicanconf.py file:

#python
   IMAGE_PREVIEW_THUMBNAILER_INSERTED_HTML = ' 🖼️'

Insert the following CSS rules:

#css
   .preview-thumbnail { display: none; }
   .previewable:hover + .preview-thumbnail { display: block; }

This configuration will ensure that only a “🖼️” icon is initially added after image links, and the thumbnail will only be displayed when the user hovers over the icon.

Integration with Images Lazyloading

If your Pelican template makes use of an images lazyloading library, you can customize the IMAGE_PREVIEW_THUMBNAILER_INSERTED_HTML configuration option to take advantage of it. For example, if you use lazysizes, follow these steps:

Define the following lines in your pelicanconf.py file:

#python
   IMAGE_PREVIEW_THUMBNAILER_INSERTED_HTML = '''
       
   '''

Now, when the image preview thumbnail is displayed, it will benefit from the lazyloading provided by the library you’re using.

Customization and Configuration

The Image Preview Thumbnailer plugin offers various configuration options that you can customize according to your needs. These options can be set in your pelicanconf.py file:

IMAGE_PREVIEW_THUMBNAILER_INSERTED_HTML: The HTML code to be inserted after every image link to preview it (default: <a href="{link}" target="_blank" class="preview-thumbnail"><img src="{thumb}" class="preview-thumbnail"></a>)
IMAGE_PREVIEW_THUMBNAILER_IGNORE_404: Avoid raising exceptions when image links result in 404 errors (default: False)
SILENT_HTTP_ERRORS: Avoid raising exceptions when image links result in HTTP errors (default: True)
IMAGE_PREVIEW_THUMBNAILER_DIR: Directory where thumbnail images are stored (default: thumbnails)
IMAGE_PREVIEW_THUMBNAILER_EXCEPT_URLS: Comma-separated list of regex patterns of URLs to ignore
IMAGE_PREVIEW_THUMBNAILER_THUMB_SIZE: Size in pixels of the generated thumbnails (default: 300)
IMAGE_PREVIEW_THUMBNAILER_ENCODING: Encoding to use to parse HTML files (default: utf-8)
IMAGE_PREVIEW_THUMBNAILER_HTML_PARSER: Parser that BeautifulSoup will use to parse HTML files (default: html.parser)
IMAGE_PREVIEW_THUMBNAILER_CERT_VERIFY: Enforce HTTPS certificates verification when sending linkbacks (default: False)
IMAGE_PREVIEW_THUMBNAILER_REQUEST_TIMEOUT: Time in seconds allowed for each HTTP linkback request before abandoning (default: 3)
IMAGE_PREVIEW_THUMBNAILER_SELECTOR: CSS selector to target HTML elements the plugin will parse for image links (default: body)
IMAGE_PREVIEW_THUMBNAILER_USERAGENT: The User-Agent HTTP header to use while sending notifications (default: pelican-plugin-image-preview-thumbnailer)
IMAGE_PREVIEW_THUMBNAILER: Enable the plugin on all your pages (default: False)

To apply any of these configuration options, simply add the corresponding variable assignment in your pelicanconf.py file.

Contributing and Release Notes

Contributions to the Image Preview Thumbnailer plugin are welcome and much appreciated. If you’d like to contribute, you can start by improving the documentation, adding missing features, or fixing bugs. You can also review and comment on existing issues on the GitHub repository.

When you’re ready to contribute, make sure to review the Contributing to Pelican documentation, specifically the Contributing Code section.

To stay up to date with the latest release notes, review the CHANGELOG.md.

Linting and Testing

To ensure the quality of your code and test its functionality, you can use the following commands:

#
pylint *.py
pytest

These commands will run the pylint linter and execute the tests respectively.

In conclusion, the Image Preview Thumbnailer plugin is a powerful tool for enhancing your Pelican website with eye-catching image preview thumbnails. With its easy installation and configuration, support for various link formats, and options for customization, this plugin is a must-have for any Pelican user. Start using it today and take your website to the next level!

If you have any questions or need further assistance, please feel free to ask.

References:
– Image Preview Thumbnailer GitHub Repository
– Pelican

Group Sum