An ag(e)ing hacker, Luca Saiu's blog
2022-11-21 01:33 (last update: 2022-11-21 23:53) Luca Saiu

I wrote a script generating an image gallery suitable to be included in web pages. Since it can be generally useful I cleaned it up and published it, of course as free software; you are welcome to download a copy of make-gallery from The software is released under the GNU General Public Licence version 3 or later; the generated code is in the public domain.

I hate the web

I have never made a mystery of my personal dislike for the web with its gratuitous ever-growing complexity, inefficiency, lack of expressivity, hostility to the developer and to the general user.

I remain adamant that the web must at some point be destroyed and replaced with a better system1; but if in the mean time we want to publish documents on the web we can abstract away the ugly part and use a script to machine-generate some HTML, CSS, JavaScript code: supply the script with a list of image files, and obtain a directory suitable to be copied to a web server.

I dirtied my hands with these things, more or less once and for all, lifting the burden from my future self and from you.


As it happens to many other pieces of software that eventually get published I started writing make-gallery to solve a contingent problem: E. and I wanted to show our wedding photos to our friends and relatives.

For that special occasion we had more than 200 photos taken; while I published a few in Hackers getting married ( most are private. Navigating through a long series of images in a simple directory listing as generated by Apache quickly gets boring, particularly for the need of going back to a main directory after displaying each picture: the process requires too many clicks and too much precision, is distracting and unpleasant, and makes it easy to make mistakes and move to the wrong point.

We needed something simple but different: a page with thumbnails and easy controls (mouse and keyboard) to move from any image to the previous and the next one. I wanted a free-software solution, did not know of any, and certainly did not want to learn to use some tool when I could hack together some simple bash script.

As is often the case with the web the problem turned out to be a little more complicated than expected, but the end result looked pretty.

The script was useful enough to deserve a cleanup and a good GNU-style command-line interface.

My galleries

I have used make-gallery to make some images easier to access and navigate on this web site. There are galleries for my hand-made APL keyboard (which is surprisingly popular with APL programmers, if I am to trust the server logs), screenshots from some old software of mine I still have to document (NAUSEA, written with Dario Russo in 2005 and AutoPatente, written by me around 2000 — please forgive some naïveté); and then there are my more recent Russian phonetic keyboards.

This is how the main page of a gallery looks like, using a CSS style which is consistent with my web site:


From the main page a user may click on any thumbnail to see a picture full-screen, or see the images in order by using arrow keys: with the right arrow one explores image from the first to the last, and with the left the other way around.


Each “full-screen” image shows a thumbnail for the previous and the next image. A user can click on them, or again navigate with the arrow keys. Going “left” from the first image or “right” from the last has the effect of returning to the main page of the gallery.


From the user’s point of view this is all, more or less. Galleries are supposed to work well on mobile devices as well; I tested on my Replicant.

Improving make-gallery

The Bash code is reasonably clean and readable.

The JavaScript code is simple-minded, and there is a separate HTML file generated for each image. The generated gallery can certainly be optimised to improve load time when moving from image to image, and I might do that at some point. I accept contributions as long as the JavaScript code does not grow in size to an unreasonable degree.
This is in fact a perfect example of a JavaScript system that must have exactly zero dependencies.

At the present time I do not guarantee future compatibility; in particular CSS classes might change.

Using make-gallery

The script requires GNU Bash, the ImageMagick convert tool and (probably) the GNU flavour of some Unix utilities. Other than that there are no dependencies or data files to read at generation time, and the make-gallery generator is a single file that can be copied anywhere in $PATH and run: I have only tested the script on GNU/Linux but it should be easy to make truly portable, by checking for command-line tool dependencies at startup.

The user is free to customise the gallery style by providing a user CSS file along with the images, at generation time; I am distributing an example of such a CSS style at User CSS definitions override the default style.

The user may also provide a favicon, and some custom HTML to display in several places in the generated gallery.

Optionally the script also generates a downloadable tar archive of the images, linked from the main page.

I use the following command line to regenerate the Russian keyboard gallery:

make-gallery \
  --verbose \
  --title 'My hand-made Russian (phonetic) keyboards from 2018 and 2020' \
  --output output-directory \
  --css \
  --favicon \
  --exit-html 'You may want to go back to <a href="">my small hacks</a> page.' \
  --bottom-html 'Copyright &copy; 2018, 2020, 2022 Luca Saiu.  Verbatim copying and redistribution of this entire page are permitted provided this notice is preserved.' \

The CSS style at, currently quite dirty, contains some definitions specific to galleries to make them fit well in the style of my web site.

More information

I will not write a full manual for such a simple software. There is support for GNU-style command-line options including --version and --help, which for a low-effort project will be enough.

make-gallery --help


make-gallery -o OUTPUTDIRECTORY [option...] [INPUTFILE...]
Generate an HTML image gallery suitable for web pages.

Common GNU-style options:
  -?, --help                        give this help list;
      --usage                       give a short usage message;
  -V, --version                     print program version.

Debugging or interaction options
      --verbose                     be verbose while processing
      --no-verbose                  do not be verbose (default)

Output options
  -o, --output,
      --output-directory DIRECTORY set the output directory (mandatory option).
  -t, --title TITLE                set the gallery name
  -l, --language CC                specify a two-letter language code
  +t, --no-tar                     do not make a tar archive (default)
  -T, --tar                        make a tar archive
      --summary                    generate a summary at the end of the main
      --no-summary                 omit the summary at the end of the main
                                   page (default)
      --date                       show the gallery generation date on the main
                                   page (default)
      --no-date                    omit generation date from the main page
      --favicon URLORPATH          specify a favicon (none by default)
      --css URLORPATH              specify a CSS file or URL, to take
                                   precedence over the default (none by default)
      --no-css                     do not use a custom CSS (default)
      --main-page-credits          show make-gallery credits on the main page
      --no-main-page-credits       omit main-page make-gallery credits
      --every-image-credits        include make-gallery credits on every image
      --no-every-image-credits     omit make-gallery credits from every image
                                   page (default)

User HTML to include in generated pages as given.
      --main-page-top-html HTML    HTML to be included literally, inside a
                                   paragraph, at the beginning of the main page
      --main-page-bottom-html HTML Like above at the end of the main page
      --image-top-html HTML        Like above at the beginning of image pages
      --image-bottom-html HTML     Like above at the end of image pages
      --top-html HTML              Like above at the beginning of every page
      --bottom-html HTML           Like above at the end of every page
      --exit-html HTML             Like above near the end of every pages; this
                                   is meant to contain a link to some page "out"
                                   of the gallery

Scaling options
      --thumb-size SIZE            linear size of thumbnails in pixels
                                   (default: 150)
      --image-size SIZE            linear size of images (default: unscaled)

Input options
      --inputs FILENAME            read other inputs from the given file,
                                   one per line.  Can be used more than once.
                                   If FILENAME is - read from stdin.

Synonymous options, be they long or short, have the same arguments; option
arguments, when supported, are always mandatory.  Option arguments must be
separated from options with whitespace, and not with equal signs.
For example: --output-directory /tmp/foo
             --output /tmp/foo
             -o /tmp/foo
but not:
When multiple options conflict the last one on the command line takes

make-gallery home page:
For reporting bugs:

About the software

make-gallery’s source code is available from the git repository at

Copyright © 2022 Luca Saiu
Copyright © 2022 p≡p Foundation
Written by Luca Saiu 

make-gallery is free software, distributed under the GNU General Public Licence version 3 or later. make-gallery comes with absolutely no warranty.

The HTML, CSS and JavaScript code generated by make-gallery is released into the public domain, up to the extent of the applicable law.

— Luca Saiu, 2022-11-21 01:33 (last update: 2022-11-21 23:53)

angle-brackets, apl, autopatente, bash, code-generation, command-line, css, english, free-software, gallery, gnu, gnu-linux, graphics, hacking, html, imagemagick, images, javascript, keyboard, make-gallery, minimalism, myself, nausea, p≡p, russian, script, software, thumbnail, unix

Next post Previous post

You might want to go to the main blog index (Atom feedfeeds for every post: Atom 1.0, RSS 2.0) or to my web site

[my photo]
Luca Saiu

The opinions I express here are my own and do not necessarily reflect the beliefs or policies of my employer or for that matter of anyone else. In case you felt that the public statement of my thoughts threatened your warm sense of security and your emotional stability feel free to leave at any time.
The system does not support user comments and probably never will. Anyway you can contact me if you want to discuss some topic with me. I might update my posts if you provide interesting insights.

You might be interested in my web site

Copyright © 2009, 2011-2014, 2017, 2018, 2021-2024 Luca Saiu
Verbatim copying and redistribution of this entire page are permitted in any medium without royalties, provided this notice is preserved.
This page was generated by
trivialblog. trivialblog is free software, available under the GNU GPL.
Tag icon copyright information is available in this file.



Notice that mobile apps are in fact much worse than the web: they are even more unfriendly to user changes and customisation, imposing gratuitous heavy restrictions of both technical and legal nature.