aboutsummaryrefslogtreecommitdiff
path: root/ldgallery.1.md
diff options
context:
space:
mode:
authorNotkea2020-01-10 22:31:47 +0100
committerGitHub2020-01-10 22:31:47 +0100
commit7042ffc06326fa8ffe70f5a59747709250166c16 (patch)
treedbfc7567bd106e03a47b499d2a07cecb6b8d6305 /ldgallery.1.md
parentc9264b0a0a7e1cb92ef7d9a391cee2c94376cff3 (diff)
parent27b51018525dbb7a6edb3073819d82245387ddd3 (diff)
downloadldgallery-7042ffc06326fa8ffe70f5a59747709250166c16.tar.gz
Merge pull request #34 from pacien/develop
first working prototype
Diffstat (limited to 'ldgallery.1.md')
-rw-r--r--ldgallery.1.md147
1 files changed, 147 insertions, 0 deletions
diff --git a/ldgallery.1.md b/ldgallery.1.md
new file mode 100644
index 0000000..981dda7
--- /dev/null
+++ b/ldgallery.1.md
@@ -0,0 +1,147 @@
1---
2pagetitle: User manual - ldgallery
3title: LDGALLERY(1) ldgallery user manual
4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-01-05 (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. Defaults to the current directory.
29
30-o, \--output-dir=_DIR_
31: Generated gallery output path. Defaults to ./out.
32
33-r, \--rebuild-all
34: Invalidate cache and recompile everything.
35
36-w, \--with-viewer
37: Include the static web viewer in the output.
38
39-h, \--help
40: Display help message.
41
42\--version
43: Print version information.
44
45\--numeric-version
46: Print just the version number.
47
48
49# INPUT GALLERY STRUCTURE
50
51A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
52Directory thumbnails can be set by placing a picture file named "thumbnail", with any image file extension, inside of it.
53
54An example input gallery directory structure could be as follows:
55
56```
57./example-gallery
58├── DSC0001.jpg --------- a picture
59├── DSC0001.jpg.yaml ---- its associated sidecar metadata file
60├── Some directory ------ a directory grouping gallery items
61│ ├── thumbnail.jpg --- a thumbnail for its parent directory
62│ ├── DSC0002.jpg
63│ ├── DSC0002.jpg.yaml
64│ ├── DSC0003.jpg
65│ └── DSC0003.jpg.yaml
66└── gallery.yaml -------- gallery settings file
67```
68
69
70# ITEM METADATA SIDECAR
71
72Item metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
73When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
74Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
75
76title
77: Title of the item. Defaults to the name of the file.
78
79datetime
80: ISO 8601 zoned date and time. Defaults to the last modification time of the file.
81
82description
83: Description for the item.
84
85tags
86: List of tags for the item. Tag groups can be defined using prefixes separated by "." (dot).
87
88
89# GALLERY CONFIGURATION
90
91The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory.
92
93compiler.galleryName
94: Name of the gallery. Defaults to "Gallery".
95
96compiler.includeFiles[]
97: Glob patterns of file names to include in the gallery. Defaults to ["*"] (matches all file names).
98
99compiler.excludeFiles[]
100: Glob patterns of file names to exclude from the gallery. Defaults to [] (none).
101
102compiler.tagsFromDirectories
103: How far to look at parent directories to add implicit tags. Defaults to 0.
104
105compiler.thumbnailMaxResolution.width
106: Maximum width in pixels of the item thumbnails, 400 by default.
107
108compiler.thumbnailMaxResolution.height
109: Maximum height in pixels of the item thumbnails, 400 by default.
110
111compiler.pictureMaxResolution.width
112: Maximum width in pixels of the picture items, unlimited by default.
113
114compiler.pictureMaxResolution.height
115: Maximum height in pixels of the picture items, unlimited by default.
116
117viewer.defaultSearchMode [TODO]
118: Default search view mode ("highlight" or "filter"). Defaults to "filter".
119
120viewer.defaultSearchQuery [TODO]
121: Default search query string.
122
123viewer.defaultSortOrder [TODO]
124: Default sort order ("alphanumeric", "reverse-alphanumeric", "date", "reverse-date"). Defaults to "date".
125
126viewer.tagGroups[].tag [TODO]
127: Tag prefix defining the tag group.
128
129viewer.tagGroups[].order [TODO]
130: Order in which to display tag groups.
131
132viewer.tagGroups[].colour [TODO]
133: Colour associated to the tag group.
134
135viewer.hiddenTags [TODO]
136: List of tags to hide by default. Items bearing one of those tags will not be displayed until they are being explicitly searched for.
137
138
139# SEE ALSO
140
141The ldgallery source code is available on <https://ldgallery.pacien.org>.
142
143Copyright (C) 2019-2020 Pacien TRAN-GIRARD and Guillaume FOUET.
144
145This 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.
146
147This 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>.