Configuration

The files organisation is quite simple:

in the root directory of your project you need a settings.yaml file that contains the title and subtitle of your gallery

for each gallery you need a folder that also contains a settings.yaml file that describes how to display the content in your gallery

and you put the pictures of the gallery inside the gallery folder

or other directory, in the gallery became an index (so pictures won’t be display, only cover of child gallery)

Root settings.yaml

The root settings.yaml should contain 2 keys: one for the title of your website and one for the subtitle. It should look like that:

title: My exploration of the outside world
sub_title: it's a scary place, don't go there

It can also optionally contain a menu and global settings.

Menu

It is possible to add a menu to your homepage that links to static pages. To do so, add a menu key to your settings.yaml, for example:

title: "About"
menu:
  - about: "About"
  - first_gallery: "My first gallery"
  - https://twitter.com: "Twitter"

For example, this could be the content of settings.yaml in about folder:

title: "About"
static: true
public: false
sections:
  - type: text
    text: Some text, HTML <b>is allowed</b>.

You can use the static option to get a template closer to the one of the homepage that is better suited for a static page. You’ll need to specify “public: false” if you don’t want to list this page on the homepage. If you don’t specify “public: false” you need to specify a “cover:” entry like any other gallery.

NOTE: expect the “static: “ option to disappear quite soon for a more generic approach to “choose your page style”.

Include Files

You can include files with the include option. These files will be copied as is from the root of your project directory to the build directory. Example:

title: My photos
sub_title: wow
include:
    - robots.txt
    - .well-known/brave-rewards-verification.txt

Global settings

Global settings can be put in your root settings.yaml, under the settings key.

GM

Currently a gm setting key allows to customize the default behaviour for thumbnail creation. It looks like:

title: Gallery
settings:
  gm:
    quality: 75
    auto-orient: True
    strip: True
    resize: 50%
    progressive: True

The meaning of the currently supported settings is as follows:

quality allows to customize the compression level of thumbnails (between 0 and 100)

auto-orient changes the orientation of pictures so they are upright (based on corresponding EXIF tags if present)

strip removes all profiles and text attributes from the image (good for privacy, slightly reduce file size)

resize can be used to resize the full-size version of pictures. By default, input image size is preserved

progressive converts classic baseline JPEG files to progressive JPEG, and interlaces PNG/GIF files (improves the page loading impression, slightly reduces file size)

Any of thumbnail creation settings can be customized on a per-image basis (either cover or image, see below).

Video converter

recitale can use ffmpeg or libav and each can be configured if needed:

title: Gallery
settings:
  ffmpeg:
    binary: "ffmpeg"
    loglevel: "error"
    format: "webm"
    vbitrate: "3900k"
    abitrate: "100k"
    audio: "libvorbis"
    video: "libvpx"
    other: "-qmin 10 -qmax 42 -maxrate 500k -bufsize 1500k"

The meaning of the currently supported FFMPEG or LIBAV’s settings is as follows:

binary sets the binary to use to convert the video (ffmpeg or avconv)

loglevel sets the logging level used by the library

format forces input or output file format

vbitrate sets video bitrate

abitrate sets audio bitrate

audio sets the audio codec

video sets the video codec

extension sets the extension of output file

other sets different options if you need more

example for MP4:

title: Gallery
settings:
  ffmpeg:
    binary: "ffmpeg"
    format: "mp4"
    audio: "acc"
    video: "libx264"
    extension: mp4

Audio converter

recitale can use ffmpeg to reencode audio and can be configured if needed:

title: Gallery
settings:
  ffmpeg_audio:
    binary: "ffmpeg"
    loglevel: "error"
    audio: "libvorbis"
    extension: "mp3"

The meaning of the currently supported FFMPEG settings is as follows:

binary sets the binary to use to convert the audio (ffmpeg by default)

loglevel sets the logging level used by the library

audio sets the audio codec

extension sets the extension of output file

example for MP3:

title: Gallery
settings:
  ffmpeg_audio:
    binary: "ffmpeg"
    loglevel: "error"
    audio: "libmp3lame"
    extension: "mp3"

Light Mode

To enable the light mode:

title: Gallery
settings:
  light_mode: true

With this option Prospopee makes a subdirectory with light version of your gallery. This light gallery uses less JS, pictures in low size, etc.

To access this light gallery, add /light at the end of the URL of the gallery.

If you want only light theme, see Themes.

Night Mode

To enable the night mode, which is only available for exposure theme (default theme):

title: Gallery
settings:
  night_mode: true

After that you will be able to choose between dark theme or light theme when visiting the website.

Themes

recitale supports different themes. As for now, only 3 themes are available:

the default one called “exposure”

light

To specify the theme, add the “theme” key in your “settings” key or your root settings.yaml. For example:

title: My exploration of the outside world
sub_title: it's a scary place, don't go there
settings:
  theme: light

Licence

By default recitale uses CC-BY-SA for all the content. If you want to use another licence, you need to add a “licence” key in root settings.yaml. For example:

title: Gallery
licence:
  name: WTFPL
  url: "https://www.wtfpl.net/txt/copying/"

RSS

To activate the RSS feed you need to add the “rss” key in root settings.yaml:

title: Gallery
rss: true
url: "https://recitale.org"

Open Graph Meta

To activate the Open Graph Meta you need to add the “og” key in root settings.yaml:

title: Sur les chemins
url: "https://recitale.org"
settings:
  og: true

You can also specify a description and a language (“lang” key) for a gallery.

For more information about Open Graph https://ogp.me/

Deployment

If you want to configure the deployment of your website with rsync:

title: Gallery
settings:
  deploy:
    ssh: true (optional, for ssh)
    username: username (optional, for ssh)
    hostname: server.com (optional, for ssh)
    dest: /var/www/website/build/
    others: --delete-after (optional)

Reverse order

Normally recitale builds the gallery index in anti-chronological. If you want to have it in chronological order, use the “reverse” key:

settings:
  reverse: true

This option can also be used in a gallery settings.yaml if you use multi-level galleries:

title: Multi level gallery
reverse: true

Password access

If you want to protect all the website by password:

title: Gallery
password: my_super_password

Please note that only the HTML page will be password-protected. Media content such as images, videos and audio files can still be accessed without password if someone knows or guesses their URL inside a password-protected gallery.

Date locale

By default, recitale uses locale from LC_TIME environment variable to generate human-readable date.

For example, if your LC_TIME equals to en_US.utf8, then you get “23 August 2020” as date on the gallery tile. If you are using ru_RU.utf8, then you get “23 Августа 2020”.

If you want to use non-based on LC_TIME locale for human-readable dates on gallery, use the “date_locale” key:

settings:
  date_locale: ru_RU

Hide gallery date

By default, recitale shows dates for all galleries in the landing page, just below each gallery title. However, you can hide it by setting the “show_date” setting to “False” in root settings.yaml:

title: My exploration of the outside world
sub_title: it's a scary place, don't go there
show_date: False

Gallery settings.yaml

This settings.yaml will describe:

the title, subtitle and cover picture of your gallery that will be used on the homepage

the tags, which are optional

if your gallery is public (if not, it will still be built but won’t appear on the homepage)

the date of your gallery that will be used on the homepage since galleries are sorted anti-chronologically

the list of sections that represents your gallery. A section represents either one picture, a group of pictures or text. The different kinds of sections will be explained in the next README section.

Example

title: Gallery title
sub_title: Gallery sub-title
date: 2016-01-15
cover: my_cover_picture.jpg
description: Some text
lang: en_US
tags:
  - #yolo
  - #travel
sections:
  - type: full-picture
    image: big_picture.jpg
    text:
      title: Big picture title
      sub_title: Some text
      date: 2016-01-15
  - type: pictures-group
    images:
      -
        - image1.jpg
        - image2.jpg
        - image3.jpg
      -
        - image4.jpg
        - image5.jpg
  - type: text
    text: Some text, HTML <b>is allowed</b>.
  - type: bordered-picture
    image: another_picture.jpg

And here is an example of a private gallery (notice the public keyword):

title: Gallery title
sub_title: Gallery sub-title
date: 2016-01-15
cover: my_cover_picture.jpg
public: false
sections:
    - ...

Advanced settings

Image handling

Images go into the cover or image keys. Each image individual processing settings can be customized to override the default GraphicsMagick settings defined (or not) in the root settings.yaml.

This is done by putting the image path into a name key, and adding specific processing settings afterwards.

For example, you can replace:

image: image1.jpg

by:

image:
  name: image1.jpg
  quality: 90
  strip: False
  auto-orient: False

Password access

You can restrict access to a gallery with a password:

title: Gallery title
sub_title: Gallery sub-title
password: my_super_password

Configuration

Root settings.yaml

Menu

Include Files

Global settings

GM

Video converter

Audio converter

Light Mode

Night Mode

Themes

Licence

Share

RSS

Open Graph Meta

Deployment

Reverse order

Password access

Date locale

Hide gallery date

Gallery settings.yaml

Example

Advanced settings

Image handling

Password access