Plugins » Images

Gives sane de­faults to im­ages and fig­ures and provides a way to present beau­ti­ful im­age gal­ler­ies.

How to use

Pel­ic­an

Down­load the m/im­ages.py file, put it in­clud­ing the m/ dir­ect­ory in­to one of your PLUGIN_PATHS and add m.images pack­age to your PLUGINS in pelicanconf.py. This plu­gin as­sumes pres­ence of m.htmls­an­ity. The fol­low­ing shows the min­im­al con­fig­ur­a­tion to­geth­er with de­fault val­ues of all avail­able op­tions. Not spe­cify­ing the op­tion is equi­val­ent to set­ting it to a de­fault value.

PLUGINS += ['m.htmlsanity', 'm.images']
M_IMAGES_REQUIRE_ALT_TEXT = False

To use the im­age grid fea­ture and im­age/fig­ure :scale: op­tion (see be­low), in ad­di­tion you need the Pil­low lib­rary in­stalled. Get it via pip or your dis­tri­bu­tion pack­age man­ager:

pip3 install Pillow

Py­thon doc theme

Simply list the plu­gin in your PLUGINS. The m.htmls­an­ity plu­gin is avail­able al­ways, no need to men­tion it ex­pli­citly. The same de­pend­en­cies as for Pel­ic­an ap­ply here. The fol­low­ing shows the min­im­al con­fig­ur­a­tion to­geth­er with de­fault val­ues of all avail­able op­tions. Not spe­cify­ing the op­tion is equi­val­ent to set­ting it to a de­fault value.

PLUGINS += ['m.images']
M_IMAGES_REQUIRE_ALT_TEXT = False

Doxy­gen theme

The Doxy­gen theme makes the built­in @image com­mand be­have sim­il­arly to the .. image:: dir­ect­ive of this plu­gin, if you add a title to it, it be­haves like .. figure::. It’s pos­sible to add ex­tra CSS classes by pla­cing @m_class in a para­graph be­fore the ac­tu­al im­age, see the Doxy­gen theme-spe­cif­ic com­mands for more in­form­a­tion. The .. image-grid:: func­tion­al­ity is not avail­able in the Doxy­gen theme.

Im­ages, fig­ures

The plu­gin over­rides the built­in im­age and fig­ure dir­ect­ives and:

  • Adds .m-image / .m-figure CSS classes to them so they have the ex­pec­ted m.css im­age and fig­ure styl­ing.
  • Re­moves the :align: op­tion, as this is bet­ter handled by m.css fea­tures and re­moves the re­dund­ant :figwidth: op­tion (use :width: in­stead).
  • The ori­gin­al :width:, :height: and :scale: op­tions are sup­por­ted, only con­ver­ted to a CSS style at­trib­ute in­stead of us­ing de­prec­ated HTML at­trib­utes. The width/height op­tions take CSS units, the scale takes a per­cent­age.
  • To main­tain ac­cess­ib­il­ity easi­er, makes it pos­sible to en­force :alt: text for every im­age and fig­ure by set­ting M_IMAGES_REQUIRE_ALT_TEXT to True.

You can add ad­di­tion­al CSS classes to im­ages or fig­ures via the :class: or :figclass: op­tions, re­spect­ively. If you want the im­age or fig­ure to be click­able, use the :target: op­tion. The alt text can be spe­cified us­ing the :alt: op­tion for both im­ages and fig­ures.

.. image:: flowers.jpg
    :target: flowers.jpg
    :alt: Flowers

.. figure:: ship.jpg
    :alt: Ship

    A Ship

    Photo © `The Author <http://blog.mosra.cz/>`_
A Ship
Photo © The Au­thor

Im­age grid

Use the .. image-grid:: dir­ect­ive for cre­at­ing im­age grid. Dir­ect­ive con­tents are a list of im­age URLs, blank lines sep­ar­ate grid rows. The plu­gin auto­mat­ic­ally ex­tracts size in­form­a­tion and scales the im­ages ac­cord­ingly. The im­ages are made click­able, the tar­get is the im­age file it­self.

If the im­age has EXIF in­form­a­tion, prop­er­ties such as aper­ture, shut­ter speed and ISO are ex­trac­ted and dis­played in the cap­tion on hov­er. It’s also pos­sible to provide a cus­tom title — everything after the fi­le­name will be taken as a title. If you use .. as a title (a reST com­ment), it will dis­able EXIF ex­trac­tion and no title will be shown.

Ex­ample of a two-row im­age grid is be­low. Sorry for re­using the same two im­ages all over (I’m mak­ing it easi­er for my­self); if you want to see a live ex­ample with non-re­peat­ing im­ages, head over to my blog.

.. image-grid::

    {static}/ship.jpg
    {static}/flowers.jpg

    {static}/flowers.jpg A custom title
    {static}/ship.jpg ..