![[icon]](https://learning-python.com/thumbspage/docetc/space-monkey.jpg "tap for online demo")
|
|
thumbspage — Turn Folders into HTML Image Galleries |
|---|
| Version: | 3.0.1, August 12, 2025 (changes) |
| License: | Provided freely, but with no warranties of any kind |
| Author: | © M. Lutz (learning-python.com) 2016-2025 |
| Views: | Any PC or mobile browser, local or remote |
| Builds: | Any host that runs Python 3.X and Pillow |
| Installs: | thumbspage, any Python 3.X, and Pillow |
| See also: | web page, live demo, screenshots, client |
Welcome to the thumbspage manual. This guide is meant for content creators and consumers of all kinds. It includes an overview of the program, detailed usage information, and a look at what's been upgraded in each release. Whether you consider yourself a developer or user, you'll find resources here to help you get started building and viewing image galleries with thumbspage.
Because thumbspage adds items to the images source folder and may rotate photos there, you are encouraged to read this guide first—especially its usage caution—before running thumbspage on valued picture collections. But if you're in a hurry: for a quick preview, try a live demo, packaged examples, or the code. You can also click the image above to test-drive the original use case, and take a brief tour of this program at its web page.
Because this program has evolved over time, this section summarizes the current state of using and building galleries as of thumbspage's latest version, 3.0. Later sections of this guide go into more details on this summary's topics. For more context, also see the 3.0 demo and screenshot galleries.
index.html. You can open this file by visiting the gallery's
web URL in your browser or by clicking its local version in a file explorer.
The index.html file is known as the index page; its thumbnails open
viewer pages for individual images when tapped.
Depending on the gallery, both page types may be colorized per the light or dark
display-mode setting on your device. Change your mode to see the effect.
The next sections cover these pages' usage.
An index page displays thumbnails for all the images in a gallery. Depending on how a gallery is built, resizing the window or display either reorganizes thumbnails to fit the new space or makes them accessible with horizontal scrolls as needed.
Scroll index pages vertically to view more thumbnails, using your device's
normal scrolling techniques (e.g., swipe, bar, or mousewheel). Click the
Top button at the bottom when it's available to jump to the top
of the index, and tap any thumbnail to open an image's viewer page.
A viewer page displays one image in the gallery, scaled to fit the view. Resizing the window or display automatically rescales the image to fit the new available space. In a viewer page, navigate and invoke other actions with:
About swipes: For touchscreens, perform swipe gestures on image itself, using one finger. For touchpads and mousewheels, the location of the mouse cursor does not matter for swipes, and swipes may use two fingers on touchpads. Touchpad and mousewheel swipes are more laggy than touchscreen swipes or keyboard presses and best kept short.
Also note that your system settings may invert swipe directions. A down swipe, for instance, may mean swiping toward either the bottom or top of your display, depending on your settings, and the meaning of left and right swipes can be swapped by both your settings and gallery builds. Experiment with swipes on your device to see which actions they trigger.
The following actions are available on all viewer pages:
Index tap, i key, browser back
Index, press
keyboard key i, or use your browser's back action
(a button or gesture also called Back).
Your browser's back action returns to your prior position in
the index page, and the viewer page's button or key returns
to index-page top.
Next/Prev tap,
left/right swipe, n/p key
Next or
Prev, perform a left or right swipe gesture, or
press keyboard keys n or p.
Messages appear when navigation wraps around to the first or
last image in the gallery, and some galleries may have
end-of-gallery pages.
Auto tap, a key
Auto or press keyboard key a.
Repeat to stop the slideshow. Slideshows are an automatic Next
with a delay between images and continue until toggled off.
Full tap, f key
Full
or press keyboard key f. Repeat to close fullscreen mode.
This is a quick zoom but lasts for just one page. Some browsers have
more permanent fullscreen options (e.g., F11 on Windows and Linux,
shift+command+f or upper-left green button on macOS, Hide Toolbar
on iOS, and icons on some Android browsers).
Note tap, up swipe, t key
Note,
perform an up swipe on the image itself, or press keyboard key t.
Close the note with the popup's bottom OK button, the keyboard
Enter key, or a tap anywhere outside the note. Notes remain
open for further reading until closed by the user, even after navigating to
the index or other images, or returning from a link.
? key
?.
Close the info with the popup's bottom OK button, the keyboard
Enter key, or a tap anywhere outside the info.
. key, up swipe?
. key. This action is also
triggered by an up swipe when no image notes are present. Use the
browser's back action to return to the gallery, per the popup reminder message.
Thumbspage is a Python command-line program distributed in source-code form.
To use it to build a gallery, first download and unzip its code
folder,
and install any Python 3.X
and its free
Pillow
extension. Then, run the unzipped folder's thumbspage.py
script in your console (e.g., Terminal, Command Prompt, or app), providing
gallery configuration options in any of the following forms:
user_configs.py file's assignments
option=value
The user_configs.py file resides in
the program's own install folder. It defines all available configuration options
as Python assignment statements (option = value) and documents
their roles and values. The names assigned in this file are the
options' names.
Each option can also be provided as option=value
arguments in the thumbspage.py command line, which override
assignments to same-named options in user_configs.py.
For legacy reasons, a handful of primary options are asked at
the console if their corresponding option remains set to None
in user_configs.py and they are not provided as
option=value arguments.
These inputs all have option names in the user_configs.py file
(e.g., inputThumbMaxSize); set them in that file or pass as
arguments to avoid console inputs (e.g., inputThumbMaxSize=128).
As a special case, if a first argument is passed to
thumbspage.py and it is not of the form
option=value, it is assumed to be the
pathname of the gallery's folder, where your images and configuration
files reside. This can also be provided as option name
inputImagesFolderPath via user_configs.py
or command-line argument.
In sum, option configuration is layered as follows:
user_configs.py provides the preset defaults for options of
all builds, and can be changed by users freely.
option=value arguments may provide
per-build overrides for any of the preset defaults in user_configs.py.
user_configs.py or the build's command-line
arguments.
option=value.
In the following example command lines, thumbspage.py
may be the full pathname to the program's main script, and Windows
typically spans lines with ^ or ` instead of
\ and uses py or py -3 instead
of python3:
Use options in user_configs.py, ask if console inputs are None:
$ python3 thumbspage.py
Also provide the image folder's pathname as the first argument:
$ python3 thumbspage.py folder
Also provide arguments that override user_configs.py settings:
$ python3 thumbspage.py folder option1=value option2=value
Same as prior, in shells that support spanning lines with "\":
$ python3 thumbspage.py folder \
option1=value \
option2=value
A larger example with explicit options and no console inputs:
$ python3 ~/Downloads/thumbspage/thumbspage.py . \
useDynamicIndexLayout=True \
dynamicLayoutPaddingH=\'16px\' \
inputCleanThumbsFolder=True \
inputThumbMaxSize=128 \
inputUseViewerPages=True \
popupFgColor=\'wheat\' \
popupOpacity=0.45 \
omitIndexPageLabels=True
Provide console inputs from a file using stream redirection:
$ python3 ../thumbspage.py mypix popupFgColor=\'#ddd\' < inputs.txt
Provide console inputs with a "here" document in Bash and others:
$ python3 ../thumbspage.py mypix popupFgColor=\'blue\' <<-EOF
(128,128)
EOF
In addition to named configuration options, you may also optionally configure thumbspage galleries by:
imagename.ext.note text files
in the images folder, which give the note text for the corresponding
image file (see also the NOTES.py alternative ahead)
HEADER.html and FOOTER.html
files in the images folder, whose code is added at the top and bottom
of generated index page and replaces default code
ORDER.txt, NOTES.py, and
CAPTIONS.py files in the images folder, to give
image ordering, notes, and labels, respectively
template-*.html files, used
to construct pages in the generated gallery and vital to this
program's operation (please edit with care)
If used, HEADER.html and FOOTER.html contain the
HTML code used above and below the thumbnails table in index pages. They are
advanced tools described ahead.
ORDER.txt lists one filename per line to give an
explicit image order, and NOTES.py and CAPTIONS.py
contain a Python dictionary mapping image filenames to notes and labels.
If provided, these files' content overrides and augments filename
ordering, .note text files, and filename labels.
Whether coded in .note files or the NOTES.py
dictionary, image notes may embed HTML tags and entities passed to the
browser when escaped with a leading underscore. Notes are optional.
See user_configs.py and later
sections of this User Guide for additional details on all of the above.
After running thumbspage.py to build a gallery, open the
image folder's generated file index.html (its default name)
in your browser to view the resulting gallery. To publish a
built gallery, simply install the entire image folder on the local or
remote host, with a copy, zip+unzip, or upload as needed.
Include the image folder's generated _thumbspage subfolder,
which contains scaffolding files needed to view the gallery.
For more ideas, see the 3.0 demo's build and publish scripts.
This section introduces the basics of thumbspage's roles and operation. Read this first if you're looking for a quick summary.
In short, this program allows you to view or display a folder of images in a web browser, using a format which is simple by design yet noticeably better than browser defaults, and does not require a web server except when viewing images online.
thumbspage turns an images folder into an easily viewed gallery. It automatically makes image thumbnails, an HTML thumbnail-links index page, and HTML image-viewer pages for all the images in a source folder, all of which can be broadly customized by content creators. The mostly static results can be viewed offline or online in any web browser.
In a theoretical sense, thumbspage is a program that builds another program: its results are a combination of HTML, CSS, and JavaScript, which are run by a browser. More tangibly, thumbspage simply creates presentation scaffolding for user-friendly views of a folder's images.
In a bit more detail, given a folder of image files, this program generates an HTML index page in one of two flavors, with generated thumbnail links for each image in the folder. This page's links open the full-size images using either browser-native (i.e., built-in) display, or generated HTML viewer pages.
Viewer pages in turn dynamically scale the image to your display; include links for gallery navigation, automatic slideshows, and one-page fullscreen; and open image-info popups on filename clicks, and image-description popups on button taps when enabled. On mobile and PC touch screens, swipe gestures on the image trigger viewer-page actions too.
Apart from image scaling and interactive tools, the net effect is intentionally static: generated results reflect the folder's contents at build time only, but do not require a web server, and can be viewed both offline and online in any desktop or mobile browser. As such, this program can be used both for both websites and non-web use cases, including program documentation, photo sharing, and general viewing.
When run using the techniques explored ahead, the builder program skips non-image files; uses optional header and footer HTML inserts in the index page; uses text note files for any or all images in viewer pages; makes an optional bullet list for subfolders in the images folder; and creates the output index page in the images folder itself, along with a subfolder for thumbnail images and viewer pages. The resulting gallery is complete and self-contained, and ready to be viewed or published.
After running this program, you can view or publish its results in a variety of ways:
index.html
by default).
_thumbspage
and index.html by default, respectively).
As a client example, the website that hosts thumbspage uses it for some 50 galleries today, some of which are viewable both online at the site, and offline in program download packages. For a sampling, see this site's demos. Builders can also find gallery-build pointers in thumbspage's publishing scripts, though its simple console interaction or command lines may suffice for most uses.
thumbspage began as a builder of simple index pages that used generated thumbnail images for their links, but its feature set has evolved over time in response to usage experience. Among its new highlights added in recent releases:
setting=value command-line arguments override config-file
settings;
tooltips can be enabled on all
pages;
and more.
You can read the full story on new releases ahead. Move on to the next section to start learning how to use thumbspage to view and display your photos.
This section covers the basics of viewing the galleries which thumbspage creates. It's oriented towards gallery consumers (a.k.a. users), though creators might find its functionality overview helpful too. If you're looking for details on running the program to make galleries, though, see the builders' section.
By today's standards, thumbspage galleries are straightforward and intuitive to use. They work and may be viewed on any desktop or mobile browser, and both online and offline. No extensions must be installed in browsers to view thumbspage galleries, though JavaScript should be enabled for the best user-interface (UI) experience, and some browsers have known quirks that can impact gallery behavior (there's more on JavaScript and browsers in Viewing Tips ahead).
Once built, a thumbspage gallery consists of an index page opened initially, and one viewer page per image opened from either thumbnails on the index page, or direct page-address URLs. The next sections describe how these two page types are used.
Index pages are the usual entry point into a gallery. Here's one captured on desktop and mobile browsers, and its live version.
Index pages display thumbnail images, either in a fixed table which scrolls both horizontally and vertically as needed, or arranged to fit the display's size per the 2.1 update ahead. Either way, index-page thumbnails normally open the next section's larger image-viewer pages when tapped (or clicked). By default, index pages also display the image folder's basename, and a bullet-list of links that open subfolders nested in the page's folder, if any are present.
Beginning with 2.0, thumbspage index pages also usually display a floating Top button near page bottom after a scroll, much like that in this guide. Click (or tap) Top to jump to the top of the index page immediately—to read its preface or open its first image, for example. Top appears only after you scroll down far enough, so it may not show up on smaller index pages.
An index page's subfolders links
may lead to supplemental info or nested galleries, and their behavior varies per
usage mode. When viewing galleries online, subfolder links typically open
a nested gallery's index page automatically. When viewing
offline, these links open a simple directory listing, and you'll
manually click nested galleries' index pages (e.g., index.html)
if present. These links also open directory listings for non-gallery folders
on some online servers; tap filenames to open. There's more on subfolders
ahead.
While many index pages follow the preceding norm, individual galleries can also customize it with tailored header and footer content above and below the thumbnails table. They might also use thumbnails that open raw displays instead of viewer pages, may display tooltips on mouseovers, and can opt out of either floating Top buttons or subfolder bullet lists. Experiment with galleries you visit to see which options they support.
Update: as of version 2.1, thumbspage index pages may also use either a fixed or dynamic layout. By default, index pages use the original fixed layout, which always displays the same number of columns. In dynamic layout, the thumbnails table does not scroll horizontally; instead, the number of columns is chosen to match the display size, and changes when the display is resized. Dynamic layout is an option which can be enabled when a gallery is built. If you run across this alternative, you can shrink or expand your window on PCs and mobiles with popup app windows to view fewer or more columns. On mobile in general, switching device orientation has a similar effect. See the demo.
Index-page thumbnail clicks and taps by default open viewer pages (a.k.a. image-viewer pages in this doc) to display a single image. Here's one captured on desktop and mobile, along with its live version.
