There are plenty of reasons to use a static website generator for web publishing instead of a traditional content management system. Serving static pages requires only a web server, which dramatically simplifies the required setup. This, in turn, improves security and reduces maintenance overhead, as the minimal stack has fewer potential vulnerabilities and is easier to troubleshoot and keep up to date.

Moreover, since publishing static content can be done using a lightweight web server, you can host your site on modest hardware or an inexpensive virtual private server.

That's all fine and dandy, but most static generators are designed to work with text-centric content like blog posts and long-form articles. But, what if you want to publish a photo essay or a photo gallery? Enter Expose [1], a Bash shell script for generating static photo and video galleries (see Figure 1). The script is less than a thousand lines long, but it's capable of generating rather impressive galleries and photo essays, and offers a wide range of configurable options to boot.

Figure 1: Expose generates polished and user-friendly static photo galleries.

Getting Started with Expose

Expose has only two dependencies: ImageMagick and FFmpeg. The latter is required only if you plan to publish videos. Better still, being just a regular Bash shell script, Expose requires no installation. Start with installing the required packages. To do this on Debian or Ubuntu, run the command:

sudo apt install imagemagick ffmpeg

To install the packages on openSUSE run the command:

sudo zypper in ImageMagick ffmeg

To deploy the script on your machine, clone the project's Git repository using the following command (make sure that Git is installed on your system first):

git clone https://github.com/Jack000/Expose.git

Open then the ~/bashrc file in a text editor and specify an alias that points to the expose.sh script:

alias expose=/script/location/expose.sh

Before you start using the script, you might want to edit some basic settings. You can do this either by modifying the defaults directly in the expose.sh script or creating a separate _config.sh file in the directory containing the photos you want to publish.

In the latter case, configuration may look something like this:

site_title="Title Goes Here"
theme_dir="theme1"
social_button=false
backgroundcolor="#ffffff"

Expose comes with two themes: the default theme presents photos as a gallery, while the second theme is more suitable for photo essays featuring a mixture of text and images.

Choosing the theme you want is a matter of specifying its name using the theme_dir configuration option. The social_button option lets you enable or disable sharing buttons, while the backgroundcolor option specifies the background color of the gallery.

Expose supports plenty of other options, too (Figure 2). If you want to allow visitors to download the published photos, use the download_button=true option. In this case, you also need to install the zip package using the sudo apt install zip command on Debian and Ubuntu or sudo zypper in zip on openSUSE. With the download option enabled, Expose conveniently bundles a readme file with the default copyright notice, but you can change it using the download_readme option, for example:

download_readme="CC BY-SA-NC 4.0"

Figure 2: You can use the available options to toggle sharing buttons, enable downloads, and configure other settings.

By default, Expose reduces image quality to 92%, but you can override this using the jpeg_quality option as follows: jpeg_quality=99. Want to give your visitor the option to add comments? You can enable support for the Disqus commenting service by specifying your Disqus shortname: disqus_shortname="shortname". Expose also provides a range of video-related options, and you can find them along with their brief descriptions in the expose.sh script.

Before you run the script, you need to do some preparatory work. Expose sorts images in alphabetical order, so to arrange photos, you might want to rename them. One way to do this is to use numeric prefixes (e.g., 001_foo.jpeg, 002_bar.jpeg, etc.). You can group photos in folders, and Expose generates a navigation menu based on the folder structure. To organize the folders, add numeric prefixes to them. The script strips these prefixes when generating a gallery, so they don't appear in the navigation menu. If you want to skip a certain folder, prefix it with _ (e.g., _private-photos), and Expose will ignore the folder when generating a gallery.

Using Expose couldn't be easier. In the terminal, switch to the directory containing the photos and videos you want to publish, and run the expose command. This generates a complete static gallery in the _site directory. If you want to generate a preview, run the expose -d command to create a gallery with low-resolution images. Keep in mind, though, that Expose doesn't overwrite existing images when you run the script again, so you need to delete the _site directory to regenerate the gallery with high-resolution photos.

Adding Descriptions and Settings

Adding a text description to a photo is as easy as creating a .txt file with the same file name as the photo. For example, to add a description to the 001_foo.jpeg photo, create the 001_foo.txt file with the desired text in it.

In the default theme, the specified description appears as a text overlay in the lower part of the photo. But this might not always be the most optimal text placement. Fortunately, Expose makes it possible to define text position and flow by specifying YAML configuration settings in the description file. You can specify the exact text position as well as the width and height of the text box by adding the following configuration at the beginning of the description file (all values are expressed in percent):

---
top: 15
left: 5
width: 25
height: 20
---

In this example, the top: 15 and left: 5 options instruct the script to place the text 15% from the top edge and 5% from the left edge of the photo. In addition to position, you can also specify text color using the textcolor settings:

---
top: 15
left: 5
width: 25
height: 20
textcolor: #ffffff
---

By default, the text is placed in a rectangular text box of specified width and height, but it's also possible to make the text flow around shapes using the polygon option. Using this option, you can specify multiple points using the X and Y values, thus turning the rectangular box into a polygon.

Here is how this works in practice. Use the width option to specify the width of the text box, for example:

---
width: 50
---

The X and Y coordinates of each corner of the box are as follows:

x:0,y:0-------x100,y:0
   |             |
   |             |
   |             |
x:100,y:100-----x:0,y:100

The rectangle can be defined using the polygon option with a JSON-formatted list of coordinates:

polygon:[{"x":0, "y":0}, {"x":100, "y":0}, {"x":100, "y":100}, {"x":0, "y":100}]

Knowing this, you can adjust the coordinates of each corner as well as introduce additional points with specific coordinates. For example, to add a left-to-right slope to the right side of the text box, adjust the X value of the top-right corner as follows:

polygon:[{"x":0, "y":0}, {"x":25, "y":0}, {"x":100, "y":100}, {"x":0, "y":100}]

Expose uses ImageMagick for all image manipulation tasks, and you can add processing instructions to the description file for on-the-fly image adjustments. For example, if you want to watermark a specific image add the following processing instruction to its description file:

---
image-options: /path/to/watermark.png -gravity SouthWest -geometry +10+10 -composite
---

This uses the watermark.png image from the specified location to apply a watermark at the lower-right corner of the image, with a 10-pixel margin from the edge. Need to sharpen a photo? The following option does the trick:

---
image-options: -sharpen 0x1.5
---

You can use practically any option supported by ImageMagick, so you might want to peruse the Command-Line Options page [2] if you want to make the most out of this functionality.

Instead of specifying options for individual photos, you can apply them globally to all published images. To do this, create the metadata.txt file and specify the desired options in it.

If you shoot time-lapse images, you'll be pleased to learn that Expose can automatically encode them as videos, no manual work required. Add the imagesequence keyword to the folder containing time-lapse images (e.g., 001 tokyo nightscape imagesequence) and put in the directory with the photos you want to publish. Then run the expose command, and the script transforms the image sequence into a video.

Figure 3: Expose makes it possible to add a description to each photo.

In Conclusion

Despite its simplicity, Expose is a rather capable and flexible tool for generating static photo and video galleries. It gives you full control of the publishing process and allows you to configure a wide range of options.

More importantly, the Expose tool produces galleries and essays that look exceptionally good and are easy to navigate.