Thanks to Robert Anderson’sImage Caption tag, Octopress
blogs have had the option to add captions to images for some time. There were
some limitations I wanted to improve upon so I began hacking away,
and created a block version that allows Markdown formatting in the caption text.
In addition, I enhanced the treatment of alt tags and relative widths.
First, a quick demo of the original imgcap tag, the example from Robert
Anderson’s blog. Using syntax pretty much identical to the standard Octopress
This leads to captioned images like the one to the left. It supports left,
right, and center image classes, and absolute sizing, making it fairly versatile.
One minor issue I had was the lack of separately specifiable alt text.
As a partially visually-impaired user, I’m sensitive to the needs readers who
rely on screen readers, and title text serves a different purpose from
So my first iteration was to study the built-in Octopress img tag and
incorporate its implementation of the alt tag into the imgcap tag. An example
use of the extended tag:
New Captions on the Block
OK, great, now imgcap has the alt text function of img, so I was happy.
But it still reuses the title (mouse-over) text for the caption. Since Liquid
tags can’t be split on multiple lines, longer captions lead to extraordinarily
long lines in the markdown sauce, and the caption text can’t be formatted.
So my next iteration involved studying Octopress’ built-in blocks (mostly the
block-quote and pull-quote blocks), and implementing imgcap as imgcaption.
Using the new block tag, a captioned image can be inserted as follows:
Now links, formatted text, and even raw HTML can be added to the image captions,
giving about as much versatility as I needed.
Size matters not. It’s All Relative
Unfortunately, in the original version large captions weren’t properly wrapped
to fit the image size; the shadow box expanded to fit the caption. Also, one
related limitation. The dimensions could only be expressed in absolute terms.
The solution to both requires slightly different HTML output, depending on
absolute or relative sizes are wanted for the image. For relative sizes, the
width needs to be defined for the outer shadow box span, with the inner
elements having a width of 100% to fill the shadow box, resulting in HTML
something like this:
Meanwhile, for absolute sizes, the inner elements need to be sized, and the
caption span needs to be adjusted for the margin sizes. This results in HTML
output like the following:
The Final Code
Title text adds flavor or contextual meta-information to an image which not contained within the image itself, while alt text provides the important contextual information within the image which is not contained in the surrounding text. ↩