Skip to main content

Tool for creating and managing PhotoSwipe albums in Hugo

Project description

HugoPhotoSwipe

build PyPI version Downloads

HugoPhotoSwipe is a command line application to easily create and manage PhotoSwipe albums when using the Hugo static website generator.

Useful links

Why?

I created my personal website using Hugo, so all source documents are created as Markdown files. I wanted to have photo albums on the site as well, using the PhotoSwipe viewer. I also wanted to easily set photo descriptions, quickly update albums when photos change, and have responsive image sizes and thumbnails automatically generated. HugoPhotoSwipe makes all this easily possible.

See my blog post here for more about my motivations for making this tool.

How?

PhotoSwipe requires some Javascript and a specific HTML format to work, and Hugo generally works with Markdown files. So, this program creates a markdown file for Hugo to work with based on Hugo shortcodes. These shortcode are then used to create the HTML code that PhotoSwipe needs. See the docs directory for the shortcodes.

Installation

HugoPhotoSwipe is available on PyPI, you can install it easily with pip:

$ pip install hugophotoswipe

After installation, you should have an hps command line program. Try running hps -V to check this.

Usage

This is a brief overview. See the Wiki for a full description.

Create a new directory for HugoPhotoSwipe and switch to it. For instance:

$ mkdir hugophotos
$ cd hugophotos

Next, initialize a HugoPhotoSwipe configuration with:

$ hps init

This creates a new HugoPhotoSwipe configuration file, called hugophotoswipe.yml. This is a YAML file. In this configuration file, you need to set at least the markdown_dir and output_dir variables. These are respectively the directory where the markdown needs to be placed and the directory where the processed photos need to be placed. You may also want to set the url_prefix variable, which is added before the path to the photo files.

Create a new album using:

$ hps new

HugoPhotoSwipe will ask you for the name of the new album, and create a directory with that name for you. Try to keep the names short, they are not the final title of the album. Spaces in the name are automatically replaced with underscores. In the new directory you will find an album.yml file and an empty photos directory.

At this point, you should place some photos in the photos directory and set the title field of the album in the album.yml file. You can also set the album date, the copyright line, and the filename of the coverimage. Key/Value pairs you place under the properties line will be placed in the preamble of the markdown file, so you can use them in Hugo layouts. For instance, you may want to add a country field, camera details, etc.

In the main directory (where the hugophotoswipe.yml file is), you can now run:

$ hps update

To create the markdown file, the resized photos, and will update the album.yml file. HugoPhotoSwipe creates large and small photo sizes, as well as thumbnails using SmartCrop.py.

If you now open the album.yml file, you'll notice that the fields for the photos and the hashes have been extended. Under photos: all the photos in the directory will be listed, with for each photo a file, name, alt, and caption field. The last three fields can be edited by you. Doing this can be useful for SEO of your photos, but is not required. The hashes field in the album.yml file is used to detect changes in the photos, and don't need to be edited by you.

Finally, if you want to regenerate all the markdown and resized photos, you can always use:

$ hps clean

to clean everything. This will of course not touch the original photo files.

Notes

I've noticed that thumbnails are slightly nicer with SmartCrop.js than with SmartCrop.py. So, in the hugophotoswipe.yml file, you can set the option use_smartcrop_js to True and the smartcrop_js_path to the path of the smartcrop-cli.js utility. This ensures thumbnails are created with SmartCrop.js.

HugoPhotoSwipe is free software, licensed under the GNU General Public License, version 3 or later (GPLv3). Copyright G.J.J. van den Burg, all rights reserved.

If you find a problem or want to suggest a feature, please let me know by opening an issue on GitHub. Don't hesitate, you're helping to make this project better! If you prefer email, you can contact me at gertjanvandenburg at gmail dot com.

BuyMeACoffee

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hugophotoswipe-0.3.1.tar.gz (33.2 kB view details)

Uploaded Source

Built Distribution

hugophotoswipe-0.3.1-py3-none-any.whl (28.9 kB view details)

Uploaded Python 3

File details

Details for the file hugophotoswipe-0.3.1.tar.gz.

File metadata

  • Download URL: hugophotoswipe-0.3.1.tar.gz
  • Upload date:
  • Size: 33.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.3

File hashes

Hashes for hugophotoswipe-0.3.1.tar.gz
Algorithm Hash digest
SHA256 e4ba1505c6c41265850531a78e3fe37a7edc0b012ca84ad396e632c1267d984a
MD5 e409c16f13c8969238a3c1e146b7a883
BLAKE2b-256 82fa54b351a7648f0bd46ee754cb3e995f282829e020ca2a1fa3188d6ecaf0fa

See more details on using hashes here.

File details

Details for the file hugophotoswipe-0.3.1-py3-none-any.whl.

File metadata

File hashes

Hashes for hugophotoswipe-0.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 a9e27bcb43326d21fea45fd3bd043e1b4b92d7b26260ecaf9df634a31e6dc558
MD5 264037443bd3a65bc81e90b30a379111
BLAKE2b-256 8ea309a7843685883aa68942be01f9e34a805a5ac21dfcbfc4044d7649dcbbd2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page