Markdown makes writing blog posts simple and fast, but sometimes that simplicity comes with limitations. Recently on updating this blog theme, I’m intend to include images in the post with captions, and there wasn’t a straightforward way using Markdown. While adding an img tag is very easy with Markdown, I would have to do some fiddling to insert the figure caption.

Extend Kramdown outputs

Kramdown was used as the default markdown converter in Jekyll. An img tag in the posts would output like this:

![alt text](https://frankindev.com/demo.jpg "Title Text")

to:

<p><img title="Title Text" alt="alt text" src="https://frankindev.com/demo.jpg"></p>

You can create a custom markdown processor as a plugin to change the output to HTML5 element <figure>.^{1 2} It would look like this:

<figure>
  <img src="https://frankindev.com/demo.jpg" alt="alt text" title="Title Text">
  <figcaption>Title text</figcaption>
</figure>

By doing so, every img tags in the post will convert to figure tags. However, I would not expect all the images in the post to have a figure caption. Instead, only the specific ones will output the caption. To realise this, only a small piece of JavaScript code is needed.

First, add a class in the markdown file to the image that intends to show the figure caption. For example, add .tofigure class to a img:

![alt text](https://frankindev.com/assets/img/logo.png "Title Text")
{:.tofigure}

Second, change the html contents by JavaScript (jQuery used here):

// Figure Caption
$('.tofigure').each(function() {
    $(this).replaceWith($('<figure class="img-with-caption tofigure">' + this.innerHTML + '</figure>'));
});
$('.tofigure').children('img').each(function() {
    var caption;
    caption = $(this).attr('title');
    $(this).after('<figcaption class="caption">' + caption + '</figcaption>');
});

Then, the html content will be changed to:

<figure class="img-with-caption tofigure">
    <img title="Title text" alt="alt text" src="https://frankindev.com/demo.jpg">
    <figcaption class="caption">Title Text</figcaption>
</figure>

Here, the figcaption is taken from the title text of the original image. Alternatively, you can change to more general alt text if you like.

Other images without the tofigure class will still in its original <p><img ...></p> form as introduced at the beginning of this post.

CSS styling

After that, style the image caption with CSS. I found this Slide In Image Captions that could help you styling the image and its caption.

Or, you can find many examples from https://codepen.io.

In summary, you can insert the image caption in just 3 steps:

1. Add a class to the image that you want to display the figure caption;
2. Few lines of JavaScript codes to change the html from img to figure;
3. Style the caption with magic CSS.

Step 2 and 3 can be configured globally in your JS and CSS files. While writing a blog post, only step 1 is required for the specific image(s).

Example

See a live demo below:

![figure caption demo](/assets/img/logo.png "Sample image for figure caption <3.")
{:.tofigure}