mikula

Mikula

Static image gallery generator inspired by Jekyll and JAlbum. Mikula is written in Python and supports uploads to AWS S3.

Motivation

I take a lot of pictures both on film and digitally and need a simple way to publish them on the web. I used JAlbum for a number of years. With a bit of tinkering it produced acceptable results, but I always wanted more flexibility in designing my own themes and albums. Jekyll provided an inspiration for creating Mikula - a static gallery generator written in Python.

Installation

Python

You will need Python version 3.8 or above to run Mikula. If you don't have Python 3.8 installed on your system follow the instructions on python.org.

Pip

Pip is python package manager. Check that you have the correct version installed by running:

pip --version

You should see pip version number and python path with (python 3.8) or higher at the end. If you see a different version number or get command not found install pip:

python3.8 -m pip install pip

It is also a good idea to upgrade pip to the latest version:

python3.8 -m pip install --upgrade pip

Depending on your system configuration you might want to install pip globally with sudo:

sudo python3.8 -m pip install --upgrade pip

Install Mikula with pip

With pip set up, install Mikula

pip install mikula

If you don't have administrator's privileges or don't want to install it globally, run the following command:

pip install --user mikula

When updating from a previous version:

pip install --upgrade mikula

Check your installation:

mikula --version

Getting Started with Mikula

Create a directory for your new gallery

Mikula is a command-line tool, so fire up your favourite Terminal program. Create a directory for your new gallery. For example:

mkdir ~/mikula-gallery

or

mkdir ~/Desktop/mikula-gallery

Navigate into this directory:

cd ~/mikula-gallery

or

cd ~/Desktop/mikula-gallery

Initialise Mikula

When you run

mikula init

it will create a stub gallery consisting of one album, including one picture and three pages: Home, About and Contact. Put your source files (images and text) into the source directory. Create a subdirectory for each album in the gallery. When you build your gallery it will be saved in the build directory. You can use Mikula to deploy the generated gallery to AWS S3 bucket (provided you have an AWS account with sufficient priviligies) or upload it manually to your web server. More cloud platforms might be supported in the future.

Configure AWS credentials

If you choose to use AWS S3 to host your gallery, provide Mikula with your AWS credentials by running this command:

mikula configure

This step is not required if you plan to use a different hosting method.

Build the gallery

Run

mikula build

to generate your gallery in the build directory.

Try it

You can test the results by running a local web server:

mikula serve

You gallery should be available on http://localhost:5000 Optionally, you can specify a different port number, for example:

mikula serve --port 1234

will run the server on http://localhost:1234

Deployment

Run

mikula deploy --bucket <bucket-name> --region <AWS-region>

to deploy the website on AWS S3. Alternatively, copy the content of the build directory to your web server. For example:

scp -rp build [e-mail]:/www/

will copy all the files and subdirectories from build into /www/ on your server.

Theme Customisation

Mikula themes can be customised. To create a new theme based on an existing one use the following command:

mikula customise --theme <my-awesome-theme> --prototype <default> --destination <theme-directory>

This will copy the prototype theme in the specified destination directory. The custom theme can be used with the build command:

mikula build --theme <my-awesome-theme>

Markdown metadata

You can add metadata in the beginning of your Markdown file. The metadata block starts and finishes with a line containing three dashes:

---
title: Funny cats' images
---

# Images of cats
This page contains a collection of amusing feline pictures.

The following metadata fields are recognised by Mikula:

Field	Value	Description
page_title	string	Page title displayed by the browser
title	string	Album or image title displayed on the parent page
thumbnail	file path	Name of an image file to be used as an album thumbnail
exclude_thumbnail	{true, false}	Set to true to exclude album thumbnail from the gallery. Default is false.
place_before	{true, false}	Set to place the text before the image(s). Default is false.
exif	list	Extract information from EXIF data. See below for a list of supported tags.
show_exif	{true, false}	Set to true to show minimal EXIF data below the image.
order	number	If defined, albums and images are sorted by order (low values come first)
hidden	{true, false}	When true the page or album is rendered but not included in the navigation bar. This is useful for a "thank you" page displayed after a visitor submits a contact form.
draft	{true, false}	When true the directory is skipped

You can also define your own fields and use them in the document.

Using metadata

Here is an example of how you can include metadata in your markdown document. Suppose you have an image file sunflowers.jpg which is taken with Canon EOS 450D and has the EXIF data embedded in the image file. If we now create a markdown file sunflowers.md with the following content:

---
page_title: Garden - Sunflowers
title: Sunflowers
place_before: false
exif:
    - Model
    - DateTime
    - ISOSpeedRatings
    - ShutterSpeedValue
    - FNumber
---

# {{title}}
Picture of sunflowers taken on {{exif["DateTime"]}} in my garden with {{exif["Make"]}} {{exif["Model"]}}.
ISO speed {{exif["ISOSpeedRatings"]}}, shutter speed {{exif["ShutterSpeedValue"]}} at f{{exif["FNumber"]}}.

the page rendered by Mikula will show the following text (styling removed for clarity):

Sunflowers
Picture of sunflowers taken on 2018:05:13 10:13:46 in my garden with Canon EOS 450D. 
ISO speed 100, shutter speed 1/500 at f1.4.

A list of supported EXIF tags is included in EXIF-tags.md.

Gallery configuration

Gallery configuration is stored in source/configuration.yaml.

Installing from source

If you plan to contribute to Mikula you will need to install it from the source.

Get the source

Clone the project repository from GitHub:

git clone https://github.com/RomanKosobrodov/mikula.git

Install dependencies

You will need development requirements:

pip install -r requirements-dev.txt

As always, it is a good idea to use a virtual environment.

Run Mikula

To run the package installed from source use the following command:

python -m mikula <command> <options>

Where <command> is one of init, configure, build, serve or deploy, and <options> are command arguments. Run

python -m mikula -h

to get a list of all supported commands and arguments.