Package: mikula
MikulaStatic image gallery generator inspired by Jekyll and JAlbum.
Mikula is written in Python and supports uploads to AWS S3.MotivationI 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 little 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.NameMikula is a Ukrainian version of name Nicholas.InstallationPythonYou 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 onpython.org.PipPipis python package manager. Check that you have the correct version installed by running:pip--versionYou 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 getcommand not foundinstall pip:python3.8-mpipinstallpipIt is also a good idea to upgrade pip to the latest version:python3.8-mpipinstall--upgradepipDepending on your system configuration you might want to installpipglobally withsudo:sudopython3.8-mpipinstall--upgradepipInstall Mikula with pipWithpipset up, install MikulapipinstallmikulaIf you don't have administrator's privileges or don't want to install it globally, run the following command:pipinstall--usermikulaWhen updating from a previous version:pipinstall--upgrademikulaCheck your installation:mikula--versionGetting Started with MikulaCreate a directory for your new galleryMikula is a command-line tool, so fire up your favourite Terminal program.
Create a directory for your new gallery. For example:mkdir~/mikula-galleryormkdir~/Desktop/mikula-galleryNavigate into this directory:cd~/mikula-galleryorcd~/Desktop/mikula-galleryInitialise MikulaWhen you runmikulainitit 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 thesourcedirectory. Create a subdirectory for each album in the gallery.
When you build your gallery it will be saved in thebuilddirectory. 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 credentialsIf you choose to use AWS S3 to host your gallery, provide Mikula with your AWS credentials by running this command:mikulaconfigureThis step is not required if you plan to use a different hosting method.Build the galleryRunmikulabuildto generate your gallery in thebuilddirectory.Try itYou can test the results by running a local web server:mikulaserveYou gallery should be available onhttp://localhost:5000Optionally, you can specify a different port number, for example:mikulaserve--port1234will run the server onhttp://localhost:1234DeploymentRunmikuladeploy--bucket<bucket-name>--region<AWS-region>to deploy the website on AWS S3.
Alternatively, copy the content of thebuilddirectory to your web server. For example:scp-rpbuilduser@example.com:/www/will copy all the files and subdirectories frombuildinto/www/on your server.Theme CustomisationMikula themes can be customised. To create a new theme based on an existing one
use the following command:mikulacustomise--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 thebuildcommand:mikulabuild--theme<my-awesome-theme>Markdown metadataYou 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 catsThis page contains a collection of amusing feline pictures.The following metadata fields are recognised by Mikula:FieldValueDescriptionpage_titlestringPage title displayed by the browsertitlestringAlbum or image title displayed on the parent pagethumbnailfile pathName of an image file to be used as an album thumbnailexclude_thumbnail{true, false}Set totrueto exclude album thumbnail from the gallery. Default isfalse.place_before{true, false}Set to place the text before the image(s). Default isfalse.exiflistExtract 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.ordernumberIf defined, albums and images are sorted by order (low values come first)hidden{true, false}Whentruethe page 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}Whentruethe directory is skippedYou can also define your own fields and use them in the document.Using metadataHere is an example of how you can include metadata in your markdown document. Suppose you have an image filesunflowers.jpgwhich is taken with Canon EOS 450D and has the EXIF data embedded in the image file. If we now create a markdown filesunflowers.mdwith 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 inEXIF-tags.md.Gallery configurationGallery configuration is stored insource/configuration.yaml.Installing from sourceIf you plan to contribute to Mikula you will need to install it from the source.Get the sourceClone the project repository from GitHub:gitclonehttps://github.com/RomanKosobrodov/mikula.gitInstall dependenciesYou will need development requirements:pipinstall-rrequirements-dev.txtAs always, it is a good idea to use a virtual environment.Run MikulaTo run the package installed from source use the following command:python-mmikula<command><options>Where<command>is one ofinit,configure,build,serveordeploy, and<options>are
command arguments. Runpython-mmikula-hto get a list of all supported commands and arguments.Upload to PYPIpython-mbuild--wheel--sdist
twineuploaddist/*