site logo

by Frank Lin in Front-end
2016-09-22 3 minutes to read 1 views 0 comments

Markdown makes writing blog posts simple and fast, but sometimes that simplicity comes with limitations. Recently on updating this blog theme, I wanted 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 inset the caption.

In this post, I’m attempting to solve this problem. Firstly, display the caption for specific images I included in a post. Secondly, style the image and its caption for better illustration.

Extend Kramdown outputs

For most cases, Kramdown was used as the markdown converter in Jekyll. An image tags in the posts would output like this:

![alt text]( "Title Text")


<p><img title="Title Text" alt="alt text" src=""></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:

  <img src="" alt="alt text" title="Title Text">
  <figcaption>Title text</figcaption>

By doing so, every img tag in the post will convert to figure tag. However, I would not expect every image to display the caption, only the specific images will output the caption. To realise this, only a small piece of JavaScript is needed.

First, add a class in the markdown file to the image that intend to show figure caption, here, it’s .tofigure class:

![alt text]( "Title Text")

Second, change the html outputs 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).before('<figcaption class="caption">' + caption + '</figcaption>');

Then, the html will change to:

<figure class="img-with-caption tofigure">
    <figcaption class="caption">Title text</figcaption>
    <img title="Title text" alt="alt text" src="">

Here, the figcaption is automatically got from the “Title Text” of the image. Alternatively, you can change to “alt text” if you like.

Other images without the tofigure class will still in its orginal <p><img ...></p> form as shown above.

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 on

Here, I used the jQuery lightgallery library to the figures.

Image demo

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

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

Step 2 and 3 can be configured globally in you js and css files. While writing blog post, only step 1 is required for the specific image.

![Hi, I'm here waiting for you!](/images/default.jpg "Sample image for figure caption")

See the live demo ✌ (thanks to jQuery lightgallery):

Hi, I'm here waiting for you!


Jekyll Web html JavaScript figure caption Markdown