aboutsummaryrefslogtreecommitdiff
path: root/compiler/ldgallery.1.md
diff options
context:
space:
mode:
Diffstat (limited to 'compiler/ldgallery.1.md')
-rw-r--r--compiler/ldgallery.1.md48
1 files changed, 26 insertions, 22 deletions
diff --git a/compiler/ldgallery.1.md b/compiler/ldgallery.1.md
index a60a3b1..eda6cc2 100644
--- a/compiler/ldgallery.1.md
+++ b/compiler/ldgallery.1.md
@@ -2,7 +2,7 @@
2pagetitle: Compiler user manual - ldgallery 2pagetitle: Compiler user manual - ldgallery
3title: LDGALLERY(1) ldgallery 3title: LDGALLERY(1) ldgallery
4author: Pacien TRAN-GIRARD, Guillaume FOUET 4author: Pacien TRAN-GIRARD, Guillaume FOUET
5date: 2020-04-30 (v1.0) 5date: 2020-09-19 (v2.0)
6--- 6---
7 7
8 8
@@ -13,7 +13,7 @@ ldgallery - a static web gallery generator with tags
13 13
14# DESCRIPTION 14# DESCRIPTION
15 15
16ldgallery is a static gallery generator which turns a collection of tagged pictures into a searchable web gallery. 16ldgallery is a static gallery generator which turns a collection of tagged media files into a searchable web gallery.
17 17
18The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery. 18The ldgallery compiler program processes pictures and aggregates metadata from plain text sidecar files to generate an indexed version of the gallery.
19It can optionally output a static web viewer along, which allows the content to be presented and searched through from a JavaScript-enabled web browser. 19It can optionally output a static web viewer along, which allows the content to be presented and searched through from a JavaScript-enabled web browser.
@@ -45,6 +45,7 @@ Available options are:
45 45
46-r, \--rebuild-all 46-r, \--rebuild-all
47: Invalidate cache and recompile everything. 47: Invalidate cache and recompile everything.
48 By default, the compiler skips items which haven't changed based on their modification time.
48 49
49-c, \--clean-output 50-c, \--clean-output
50: Remove unnecessary files from the output directory. 51: Remove unnecessary files from the output directory.
@@ -67,22 +68,24 @@ Available options are:
67 68
68A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories. 69A gallery source directory contains the gallery items and their sidecar metadata files, optionally grouped inside sub-directories.
69 70
70Directory thumbnails can be set by placing a picture file named "_directory", with any image file extension, inside of directories. 71Thumbnails can be associated to items by suffixing their name with "\_thumbnail", followed by an image file extension.
72Directory thumbnails can be placed within their respective directories themselves, without any prefix.
71 73
72An example input gallery directory structure could be as follows: 74An example input gallery directory structure could be as follows:
73 75
74``` 76```
75./example-gallery 77./example-gallery
76├── DSC0001.jpg --------- a picture 78├── DSC0001.jpg ----------------- a picture
77├── DSC0001.jpg.yaml ---- its associated sidecar metadata file 79├── DSC0001.jpg.yaml ------------ its associated sidecar metadata file
78├── Some directory ------ a directory grouping gallery items 80├── Some directory -------------- a directory grouping gallery items
79│ ├── _directory.jpg -- a thumbnail for its parent directory 81│ ├── _directory.yaml --------- directory sidecar metadata file
80│ ├── _directory.yaml - directory sidecar metadata file 82│ ├── _thumbnail.jpg ---------- a thumbnail for its parent directory
81│ ├── DSC0002.jpg 83│ ├── DSC0002.jpg
82│ ├── DSC0002.jpg.yaml 84│ ├── DSC0002.jpg.yaml
83│ ├── DSC0003.jpg 85│ ├── song.ogg
84│ └── DSC0003.jpg.yaml 86│ ├── song.ogg.yaml
85└── gallery.yaml -------- gallery settings file 87│ └── song.ogg_thumbnail.jpg -- a thumbnail for song.ogg
88└── gallery.yaml ---------------- gallery settings file
86``` 89```
87 90
88 91
@@ -91,7 +94,7 @@ An example input gallery directory structure could be as follows:
91File metadata are read from sidecar files of the same name, with the ".yaml" extension appended. 94File metadata are read from sidecar files of the same name, with the ".yaml" extension appended.
92Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored. 95Metadata contained within item files themselves (e.g. Exif fields for pictures) are ignored.
93 96
94Directory metadata are read from sidecar files named "_directory.yaml" located within the directory. 97Directory metadata are read from sidecar files named "\_directory.yaml" located within the directory.
95 98
96When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below. 99When a sidecar file is absent or a particular key omitted, values are set as empty or to their fallback value specified below.
97 100
@@ -99,17 +102,16 @@ title
99: Title of the item. 102: Title of the item.
100 Defaults to the name of the file or directory. 103 Defaults to the name of the file or directory.
101 104
102<!-- not used in the viewer yet --
103datetime 105datetime
104: ISO 8601 zoned date and time. 106: ISO 8601 zoned date and time.
105 Defaults to the last modification time of the file itself, 107 Defaults to the last modification time of the file itself,
106 or the most recent modification date of a directory's items. 108 or the most recent modification date of a directory's items.
107-->
108 109
109<!-- not used in the viewer yet --
110description 110description
111: Description for the item. 111: Optional description for the item.
112--> 112 Rich text formatting is possible through the use of the [GitHub Flavoured Markdown syntax][GFM].
113
114 [GFM]: https://github.github.com/gfm/
113 115
114tags 116tags
115: List of tags for the item. 117: List of tags for the item.
@@ -119,7 +121,9 @@ tags
119 121
120# GALLERY CONFIGURATION 122# GALLERY CONFIGURATION
121 123
122The gallery settings reside in a file named "gallery.yaml" located at the root of the gallery's source directory. 124The gallery settings reside in a file named __gallery.yaml__ located at the root of the gallery's source directory.
125
126Gallery configurations options are:
123 127
124galleryTitle 128galleryTitle
125: Title of the gallery. 129: Title of the gallery.
@@ -127,7 +131,7 @@ galleryTitle
127 131
128includedDirectories[] 132includedDirectories[]
129: Glob patterns of directory names to include in the gallery. 133: Glob patterns of directory names to include in the gallery.
130 Defaults to ["*"] (matches all directory names). 134 Defaults to ["\*"] (matches all directory names).
131 135
132excludedDirectories[] 136excludedDirectories[]
133: Glob patterns of directory names to exclude from the gallery. 137: Glob patterns of directory names to exclude from the gallery.
@@ -135,7 +139,7 @@ excludedDirectories[]
135 139
136includedFiles[] 140includedFiles[]
137: Glob patterns of file names to include in the gallery. 141: Glob patterns of file names to include in the gallery.
138 Defaults to ["*"] (matches all file names). 142 Defaults to ["\*"] (matches all file names).
139 143
140excludedFiles[] 144excludedFiles[]
141: Glob patterns of file names to exclude from the gallery. 145: Glob patterns of file names to exclude from the gallery.
@@ -144,7 +148,7 @@ excludedFiles[]
144includedTags[] 148includedTags[]
145: Glob patterns of tags to include in the gallery. 149: Glob patterns of tags to include in the gallery.
146 Items with no tags can be matched with the empty pattern. 150 Items with no tags can be matched with the empty pattern.
147 Defaults to ["*"] (matches all tags, includes untagged items). 151 Defaults to ["\*"] (matches all tags, includes untagged items).
148 152
149excludedTags[] 153excludedTags[]
150: Glob patterns of tags to exclude from the gallery. 154: Glob patterns of tags to exclude from the gallery.
@@ -176,7 +180,7 @@ pictureMaxResolution.height
176 180
177# SEE ALSO 181# SEE ALSO
178 182
179Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7) 183Related manual pages: __ldgallery-quickstart__(7), __ldgallery-viewer__(7).
180 184
181The ldgallery source code is available on <https://ldgallery.pacien.org>. 185The ldgallery source code is available on <https://ldgallery.pacien.org>.
182 186