aboutsummaryrefslogtreecommitdiff
path: root/ldgallery.1.md
diff options
context:
space:
mode:
Diffstat (limited to 'ldgallery.1.md')
-rw-r--r--ldgallery.1.md175
1 files changed, 0 insertions, 175 deletions
diff --git a/ldgallery.1.md b/ldgallery.1.md
deleted file mode 100644
index e891345..0000000
--- a/ldgallery.1.md
+++ /dev/null
@@ -1,175 +0,0 @@
1---
2pagetitle: User manual - ldgallery
3title: LDGALLERY(1) ldgallery user manual
4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-02-15 (v0.1.0.0-SNAPSHOT)
6---
7
8
9# NAME
10
11ldgallery - a static web gallery generator with tags
12
13
14# DESCRIPTION
15
16ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery.
17
18The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery. It can optionally output a static web viewer along, which allows the content to be presented and searched through from a JavaScript-enabled web browser. This client-side web application does not require any special software on the server's side.
19
20
21# COMMAND
22
23ldgallery [\--input-dir _./_] [\--output-dir _./out_] [\--with-viewer]
24
25Available options are:
26
27-i, \--input-dir _DIR_
28: Gallery source directory.
29 Defaults to the current directory.
30
31-o, \--output-dir _DIR_
32: Generated gallery output path.
33 Must be distinct from the source directory.
34 Defaults to ./out.
35
36-g, \--gallery-config _FILE_
37: Gallery configuration file.
38 Defaults to $input-dir/gallery.yaml.
39
40-r, \--rebuild-all
41: Invalidate cache and recompile everything.
42
43-c, \--clean-output
44: Remove unnecessary files from the output directory.
45
46-w, \--with-viewer
47: Include the static web viewer in the output.
48
49-h, \--help
50: Display help message.
51
52\--version
53: Print version information.
54
55\--numeric-version
56: Print just the version number.
57
58
59# INPUT GALLERY STRUCTURE
60
61A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
62
63Directory thumbnails can be set by placing a picture file named "_directory", with any image file extension, inside of directories.
64
65An example input gallery directory structure could be as follows:
66
67```
68./example-gallery
69├── DSC0001.jpg --------- a picture
70├── DSC0001.jpg.yaml ---- its associated sidecar metadata file
71├── Some directory ------ a directory grouping gallery items
72│ ├── _directory.jpg -- a thumbnail for its parent directory
73│ ├── _directory.yaml - directory sidecar metadata file
74│ ├── DSC0002.jpg
75│ ├── DSC0002.jpg.yaml
76│ ├── DSC0003.jpg
77│ └── DSC0003.jpg.yaml
78└── gallery.yaml -------- gallery settings file
79```
80
81
82# METADATA SIDECAR
83
84File metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
85Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
86
87Directory metadata are read from sidecar files named "_directory.yaml" located within the directory.
88
89When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
90
91title
92: Title of the item.
93 Defaults to the name of the file or directory.
94
95datetime
96: ISO 8601 zoned date and time.
97 Defaults to the last modification time of the file itself,
98 or the most recent modification date of a directory's items.
99
100description
101: Description for the item.
102
103tags
104: List of tags for the item.
105 Tag groups can be defined using prefixes separated by "." (dot).
106 Tags specified in a directory metadata sidecar are applied to all items within that directory.
107
108
109# GALLERY CONFIGURATION
110
111The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
112
113compiler.includedDirectories[]
114: Glob patterns of directory names to include in the gallery.
115 Defaults to ["*"] (matches all directory names).
116
117compiler.excludedDirectories[]
118: Glob patterns of directory names to exclude from the gallery.
119 Defaults to [] (none).
120
121compiler.includedFiles[]
122: Glob patterns of file names to include in the gallery.
123 Defaults to ["*"] (matches all file names).
124
125compiler.excludedFiles[]
126: Glob patterns of file names to exclude from the gallery.
127 Defaults to [] (none).
128
129compiler.tagsFromDirectories.fromParents
130: Automatically generate tags from the name of parent directories,
131 looking up in the hierarchy as far as indicated by this parameter.
132 Defaults to 0 (do not generate tags from parent directories).
133
134compiler.tagsFromDirectories.prefix
135: Prefix to use for tags automatically generated from the parent directories' names.
136
137compiler.thumbnailMaxResolution.width
138: Maximum width in pixels of the item thumbnails, 400 by default.
139
140compiler.thumbnailMaxResolution.height
141: Maximum height in pixels of the item thumbnails, 300 by default.
142
143compiler.pictureMaxResolution.width
144: Maximum width in pixels of the picture items, unlimited by default.
145
146compiler.pictureMaxResolution.height
147: Maximum height in pixels of the picture items, unlimited by default.
148
149viewer.defaultSearchQuery [TODO]
150: Default search query string.
151
152viewer.defaultSortOrder [TODO]
153: Default sort order ("alphanumeric", "reverse-alphanumeric", "date", "reverse-date").
154 Defaults to "date".
155
156viewer.tagGroups[].tag [TODO]
157: Tag prefix defining the tag group.
158
159viewer.tagGroups[].colour [TODO]
160: Colour associated to the tag group.
161
162viewer.hiddenTags [TODO]
163: List of tags to hide by default.
164 Items bearing one of those tags will not be displayed until they are being explicitly searched for.
165
166
167# SEE ALSO
168
169The ldgallery source code is available on <https://ldgallery.pacien.org>.
170
171Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
172
173This 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.
174
175This 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>.