plugins/thumbnailer/Readme.md

   1 Thumbnail Creation of images
   2 ============================
   3
   4 **NOTE:** [This plugin has been moved to its own repository](https://github.com/pelican-plugins/thumbnailer). Please file any issues/PRs there. Once all plugins have been migrated to the [new Pelican Plugins organization](https://github.com/pelican-plugins), this monolithic repository will be archived.
   5
   6 -------------------------------------------------------------------------------
   7
   8 This plugin creates thumbnails for all of the images found under a specific directory, in various thumbnail sizes.
   9 It requires `PIL` to function properly since `PIL` is used to resize the images, and the thumbnail will only be re-built
  10 if it doesn't already exist (to save processing time).
  11
  12 Installation
  13 -------------
  14
  15 Set up like any other plugin, making sure to set `PLUGIN_PATH` and add `thumbnailer` to the `PLUGINS` list.
  16
  17 [PIL](http://www.pythonware.com/products/pil/) or [Pillow](http://pillow.readthedocs.org/en/latest/installation.html#)
  18 is required. If you choose Pillow, you need to install some additional
  19 [external libraries](http://www.pythonware.com/products/pil/) to add support for image types like `jpg`.
  20
  21 Configuration
  22 -------------
  23
  24 * `IMAGE_PATH` is the path to the image directory. It should reside inside your content directory, and defaults to "pictures".
  25 * `THUMBNAIL_DIR` is the path to the output sub-directory where the thumbnails are generated.
  26 * `THUMBNAIL_SIZES` is a dictionary mapping size name to size specifications.
  27   The generated filename will be `originalname_thumbnailname.ext` unless `THUMBNAIL_KEEP_NAME` is set.
  28 * `THUMBNAIL_KEEP_NAME` is a Boolean that, if set, puts the file with the original name in a thumbnailname folder, named like the key in `THUMBNAIL_SIZES`.
  29 * `THUMBNAIL_KEEP_TREE` is a Boolean that, if set, saves the image directory tree.
  30 * `THUMBNAIL_INCLUDE_REGEX` is an optional string that is used as regular expression to restrict thumbnailing to matching files. By default all files not starting with a dot are respected.
  31
  32 Sizes can be specified using any of the following formats:
  33
  34 * wxh will resize to exactly wxh cropping as necessary to get that size
  35 * wx? will resize so that the width is the specified size, and the height will scale to retain aspect ratio
  36 * ?xh same as wx? but will height being a set size
  37 * s is a shorthand for wxh where w=h