This document is a step-by-step guide showing how to create and
compile a simple gallery and get familiar with
It mainly describes how to structure the source gallery directory
accepted by the ldgallery compiler.
[source gallery directory with items and their tags]
| ldgallery compiler
[generated web gallery with embedded web viewer]
initialising the gallery source directory
A new gallery can be initialised by creating a directory
containing a gallery configuration file named
└── gallery.yaml ------ gallery settings file
gallery.yaml holds the settings of the gallery.
Its content can be as follows:
# gallery.yaml: ldgallery example gallery configuration file.
# See ldgallery(1) for a list of available configuration keys.
galleryTile: Monuments of the World
Step 2: adding items
A new item, say a picture file named “DSC0001.jpg”, can now be
added to the directory created at the previous step.
Optionally, some metadata such as a title and some tags can be
associated by creating a file named “DSC0001.jpg.yaml” at the same
├── gallery.yaml ------ gallery settings file
├── DSC0001.jpg ------- a picture
└── DSC0001.jpg.yaml -- its associated optional sidecar metadata file
The sidecar metadata file “DSC0001.jpg.yaml” can have the
# DSC0001.jpg.yaml: ldgallery metadata sidecar file for DSC0001.jpg.
# See ldgallery(1) for a list of available keys.
title: The Eiffel Tower
Step 3: compiling the
The gallery can now be compiled by running the following command
in a terminal with the right path to the gallery directory created
during the previous steps:
--input-dir ./monument-gallery-source \
Running the command above produces a directory named
“monument-gallery-output” in the current directory, which contains
the compiled gallery and a web viewer ready to be copied to some web
The target web host doesn’t need to run any additional software
besides a web server correctly configured to serve flat static
Some standard version-control software such as Git or Mercurial
can easily be used to keep track of the evolutions of the gallery
directory, thanks to the text-based format used for the sidecar
The gallery can quickly be deployed by using a command such as
The compilation and upload commands can be combined in a Makefile
or made part of a script for faster and more convenient deployments.
Such scripted procedure can then further be automated through
Continuous Integration hooks.
Related manual pages: ldgallery(1),
The ldgallery source code is available on https://ldgallery.pacien.org.
Copyright (C) 2019-2023 Pacien TRAN-GIRARD and Guillaume
This program is free software: you can redistribute it and/or
modify it under the terms of the GNU Affero General Public License
as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Affero General Public License for more details https://www.gnu.org/licenses/agpl-3.0.html.