Lightbox -- A pure CSS lightbox for Pelican
###########################################

.. figure:: https://raw.githubusercontent.com/kura/lightbox/master/lightbox.png
    :alt: Lightbox
    :align: center

    Credit: `Kimberly Coles <http://www.kimberlycoles.com/>`_

.. contents::
    :backlinks: none

Introduction
============

With the release of my `Eevee <https://kura.io/eevee/>`_ theme for `Pelican
<http://getpelican.com>`_, I realised displaying a thumbnail image of the
theme that linked to a larger image wasn't the most appealing design choice.
I prefer to leave Javascript out of the equation where possible, being one of
those weird people that have it disabled by default.

As such I sought out a way to create a pure CSS equivalent of a Lightbox and
turn it in to an RST directive to plug directly in to Pelican.

Installation
============

.. code-block:: bash

    $ wget https://github.com/kura/lightbox/archive/master.tar.gz -O lightbox.tar.gz
    $ tar xvzf lightbox.tar.gz
    $ mv lightbox-master /your/pelican/plugins/folder/lightbox

Make sure to rename the ``lightbox-master`` directory to ``lightbox``.

If you do not have a plugins directory in your Pelican blog, in the root
directory of your blog, the directory your ``content`` directory is in.

Create one.

.. code-block:: bash

    $ mkdir plugins

And in your ``pelicanconf.py`` set the ``PLUGIN_PATHS`` variable.

.. code-block:: python

    PLUGIN_PATHS = ['plugins/', ]

Then add lightbox to your ``pelicanconf.py`` ``PLUGINS``.

.. code-block:: python

    PLUGINS = [
        # ...
        'lightbox',
        # ...
    ]

Usage
=====

In your article or page, you simply need add a directive.

.. code-block:: rst

    .. lightbox::
        :thumbnail: /images/eevee-thumbnail.png
        :large: /images/eevee-large.png

Will result in the following HTML.

.. code-block:: html

    <div class="align-left">
        <a href="#005da263-b70e-4a84-b8c3-e2c989527613" title="Click to view large image">
            <img src="/images/eevee-article-header-thumb.png" class="align-left" alt="Click to view large image" />
        </a>
        <a class="lightbox" href="#_" id="005da263-b70e-4a84-b8c3-e2c989527613" title="Click to close">
            <img src="/images/eevee-article-header.png" alt="Click to close" />
        </a>
    </div>
    <div class="lightbox-divider"></div>

Optional arguments
==================

Lightbox also supports the following optional arguments.

- `alt`_
- `caption`_
- `align`_

Alt
---

This optional argument defines ``alt=`` attribute for an image that is also
used the ``title=`` attribute for anchors.

.. code-block:: rst

    :alt: Eevee, the Pokémon

Caption
-------

This optional argument defines caption text for an image, it is displayed
under the thumbnail inside a paragraph ``<p></p>`` element.

.. code-block:: rst

    :caption: Eevee, the Pokémon

Align
-----

This optional argument defines the alignment of the thumbnail image and
caption.

.. code-block:: rst

    :align: center

Valid values for this option are;

- center
- left
- right

Alignment is added as a CSS class attribute, for example;

.. code-block:: html

    <img class="align-center" />
    <img class="align-left" />
    <img class="align-right" />

CSS attributes
==============

Each set of lightbox thumbnail, large image and caption are wrapped in a
``<div>`` element with the class attribute ``lightbox-block`` and a class
attribute based on the alignment i.e. ``align-left``.

For example;

.. code-block:: html

    <div class="lightbox-block align-left"> ... </div>

The thumbnail image will have an alignment class attribute too.

.. code-block:: html

    <img class="align-left" />

The large image and the anchor that closes it have the class attribute
``lightbox`` which initially sets their display as hidden.

.. code-block:: html

    <a href="#_" class="lightbox" title="Click to close">
        <img class="lightbox" alt="Click to close" />
    </a>

Finally, the parent ``div`` element is closed and a final ``div`` element with
the class attribute ``lightbox-divider`` is provided, allowing you to create a
defined separation between images.

.. code-block:: html

    <div class="lightbox-divider"></div>

Putting all elements together, this is how the final HTML will be returned.

.. code-block:: html

    <div class="lightbox-block align-center">
        <a href="#e17813e9-ba4c-4037-be9a-3b0bb81fa0e5" title="Homepage (click to view large image)">
            <img alt="Homepage (click to view large image)" class="align-center" src="/images/eevee-homepage-thumb.png" />
        </a>
        <a class="lightbox" href="#_" id="e17813e9-ba4c-4037-be9a-3b0bb81fa0e5" title="Click to close">
            <img alt="Click to close" src="/images/eevee-homepage.png" />
        </a>
        <p class="align-center">Homepage (click to view large image)</p>
    </div>
    <div class="lightbox-divider"></div>

Basic CSS for Lightbox
======================

.. code-block:: css

    .lightbox {
        display: none;
        position: fixed;
        z-index: 999;
        width: 100%;
        height: 100%;
        text-align: center;
        top: 0;
        left: 0;
        right: 0;
        bottom: 0;
        background: rgba(0,0,0,0.8);
    }

    .lightbox img {
        max-width: 98%;
        max-height: 90%;
        margin-top: 2%;
    }

    .lightbox:target {
        outline: none;
        display: block;
    }

    .lightbox-divider {
        background: #E0E0E0;
        width: 100%;
        height: 3px;
        -webkit-flex-shrink: 0;
        -ms-flex-negative: 0;
        flex-shrink: 0;
        margin: 30px 0;
    }

You can get a copy of this `basic CSS file from GitHub
<https://github.com/kura/lightbox/blob/master/lightbox.css>`_.


Source code
===========

The source code of Lightbox is `hosted on GitHub
<https://github.com/kura/lightbox/>`__.

License
=======

Lightbox is released under the `MIT license
<https://github.com/kura/lightbox/blob/master/LICENSE>`__.