hyde/hyde — pull request #259 by dandersson (2014-03-18 18:26:30+00:00)
Title: Add plugin: ImageThumbnailsPlugin

#### Plugin rationale
When using other static content generating platforms, I found that I often used available constructs to generate thumbnail links to full size images on-the-fly from within posts. The facility for generating thumbnails in Hyde via `ImageThumbnailsPlugin` is quite static in that it must be defined in the configuration files external from the blog posts. Also, to generate a linked thumbnail pointing towards a full size image, one would at first need to define the thumbnail generating configuration in the `meta.yaml`, with file name matching and hard-coded dimensions, and then write something like:

[![My dog.]([[!!images/x300-img_0001.jpg]])]([[!!images/img_0001.jpg]])

in the markup to generate the link, remembering the specific prefix.

#### Plugin description
`ImageThumblinksPlugin` (note *`links`* vs *`nails`*) enables a direct syntax for generating thumbnails from within the document. After the plugin is enabled in the site configuration, a line like this in the markup:

[[!thumblink|My dog.|x300|images/img_0001.jpg]]

will automatically generate the thumbnail itself during site generation using existing functions (parameters in the above example will be: width undefined, height 300 pixels; see the existing `ImageThumbnailsPlugin.thumb()` for information on the parameters) and create the link of the earlier mentioned form.

It does not clash with any existing functions to my knowledge. It needs to be loaded before `TextlinksPlugin` to work, though.

The code is almost over-the-top documented with inline comments, since I find that looking at the code is of great use until the Hyde documentation in general gets major updates.

---

#### Lingering issues
1. I get error messages like

17:52:33 hyde.server Cannot load file: [media/images/x300-img_0001.jpg]

from `hyde -v serve` when loading any of the thumbnails generated from this plugin. However, the images load fine in the browser. The thumbnail creation is handled fully by the functions in the existing `ImageThumbnailsPlugin` class, and those images do not give the error message. I have not been able to find the problem. As it does not affect the actual generation or the serving, I'm guessing it is some meta registration of resources that is not done correctly, for some reason.

2. I do not know if the markup syntax clashes with other plugins, or if there is a more natural syntax that should be followed by convention.

3. This plugin must be loaded before `TextlinksPlugin` in order for that plugin to post-process the generated syntax. Perhaps this could be solved by explicitly calling that plugin from within this one, but enforcing a plugin load order as right now might be clearer.

#### Possible enhancements
1. Thumbnails are automatically generated, but not automatically removed if they are removed from the post. This is also true for `ImageThumbnailsPlugin`, and is perhaps not an actual issue. Cleaning out the thumbnail folder manually solves this in a simple way. There might be use cases where one would not want to remove the thumbnail even if it is not referenced in any local posts, e.g. for external hotlinking purposes. This would be easily solved by moving the image from the `.thumbnail` folder to the `media` path, though.

2. There are more possible arguments for the thumbnail generating function that are not implemented in the `ImageThumblinksPlugin` syntax. They could be added without problem, but I personally can not really see a use case for them, and if they were to be added, it would be good to know if the current parameter syntax was OK beforehand.