Using an image caption in Markdown Jekyll

Question

I am hosting a Jekyll Blog on Github and write my posts with Markdown. When I am adding images, I do it the following way:

![name of the image](http://link.com/image.jpg)

This then shows the image in the text.

However, how can I tell Markdown to add a caption which is presented below or above the image?

Solution 1

If you don't want to use any plugins (which means you can push it to GitHub directly without generating the site first), you can create a new file named image.html in _includes:

<figure class="image">
  <img src="{{ include.url }}" alt="{{ include.description }}">
  <figcaption>{{ include.description }}</figcaption>
</figure>

And then display the image from your markdown with:

{% include image.html url="/images/my-cat.jpg" description="My cat, Robert Downey Jr." %}

Solution 2

I know this is an old question but I thought I'd still share my method of adding image captions. You won't be able to use the caption or figcaption tags, but this would be a simple alternative without using any plugins.

In your markdown, you can wrap your caption with the emphasis tag and put it directly underneath the image without inserting a new line like so:

![](path_to_image)
*image_caption*

This would generate the following HTML:

<p>
    <img src="path_to_image" alt>
    <em>image_caption</em>
</p>

Then in your CSS you can style it using the following selector without interfering with other em tags on the page:

img + em { }

Note that you must not have a blank line between the image and the caption because that would instead generate:

<p>
    <img src="path_to_image" alt>
</p>
<p>
    <em>image_caption</em>
</p>

You can also use whatever tag you want other than em. Just make sure there is a tag, otherwise you won't be able to style it.

Solution 3

You can use table for this. It works fine.

| ![space-1.jpg](http://www.storywarren.com/wp-content/uploads/2016/09/space-1.jpg) | 
|:--:| 
| *Space* |

Result:

Solution 4

The correct HTML to use for images with captions, is <figure> with <figcaption>.

There's no Markdown equivalent for this, so if you're only adding the occasional caption, I'd encourage you to just add that html into your Markdown document:

Lorem ipsum dolor sit amet, consectetur adipiscing elit...

<figure>
  <img src="{{site.url}}/assets/image.jpg" alt="my alt text"/>
  <figcaption>This is my caption text.</figcaption>
</figure>

Vestibulum eu vulputate magna...

The Markdown spec encourages you to embed HTML in cases like this, so it will display just fine. It's also a lot simpler than messing with plugins.

If you're trying to use other Markdown-y features (like tables, asterisks, etc) to produce captions, then you're just hacking around how Markdown was intended to be used.

Solution 5

A slight riff on the top voted answer that I found to be a little more explicit is to use the jekyll syntax for adding a class to something and then style it that way.

So in the post you would have:

![My image](/images/my-image.png)

{:.image-caption}
*The caption for my image*

And then in your CSS file you can do something like this:

.image-caption {
  text-align: center;
  font-size: .8rem;
  color: light-grey;

Comes out looking good!

View more solutions

Comments

[orschiro]

Thanks. So markdown alone is not capable of creating captions?

[Chongxu Ren]

I believe it depends on the converter you use, however, markdown standard doesn't support adding captions.

[orschiro]

That is a great idea! However, site_root is not accepted as a valid variable. When rendered it ends up as src="{{ site.url_root }}....

[IQAndreas]

Ah, right, that is a variable added in Octopress. I edited it out, so the sample code just uses a relative URL to the image.

[Roy Tinker]

Jekyll now includes a site.url variable.

[Corstian Boerman]

Awesome! No need to memorize some stupid jekyll syntax :)

[Edmundo Santos]

A better markup would be: <figure class="image"><img src="{{ include.url }}" alt="{{ include.description }}"><figcaption>{{ include.description }}</figcaption></figure>

[Edmundo Santos]

I need more information… it's possible to put more than one image without the need to repeat the include image.html? I'm trying with something like {% for image in page.images %} but no success. Can you help me?

[ahwillia]

I'm a big fan of this

[Michal Gruca]

Thank you! Was just searching for that

[sudo make install]

It's too bad that this answer hasn't gotten any attention--I really think it's the simplest and most semantically correct. I'm particularly distressed by all the answers suggesting formatting using tables, which just wreaks of 1990s mayhem. ;-)

[Boriel]

I agree. However it seems not to be supported by Bitbucket yet. A pitty.

[Seanba]

I like the clever and simple answer provided by @Andrew but I have to go with this one given that is explicit, makes use of the appropriate HTML tags, and doesn't require too much typing.

[ChriiSchee]

Hi there! I am not quite sure where and how to put the CSS part...it would be really great if anyone could help.

[Jan Zavrel]

@ChriiSchee Either you place it in the main CSS file, or you can create your own and link it to your default layout. For example, my default layout links to main.css file <link href="{{ site.baseurl }}/assets/css/main.css" rel="stylesheet"> so I just add my custom CSS definition at the bottom of this file: // My custom css img + em { display: block; text-align: center; } //image captions

[Kadam Parikh]

This answer is the best one.. Using pure markdown and getting what you need. Thanks!

[paulochf]

Sort of offtopic, but this also works in Jupyter Notebooks.

[Sambo Kim]

Thanks a lot, I am new to jekyll and didn't know markdown can be used with html.

[Aleix Sanchis]

Just for completeness, if you want to use jekyll-figure you will have to add jekyll-figure to plugins in your _config.yml

[Abhay Hegde]

It reduced the width from 100% for me. How do I widen it?

[cregox]

this is by far the best answer, because it reduces code (thus chances of error), uses the correct standard and, above all, works for more than just captions (i wanted to add a class to the image, for resizing and centering).

[Codemonkey]

It's a shame that CSS doesn't allow you to go up the chain, so you could target the <p> tag here based on it having an <img> and an <em>. Something like img+em < p {rules}.

[zeeshan khan]

Is there a way to format the caption as markdown rather than just text? I want to hyperlink using markdown syntax but it doesn't work. Tried kramdown too

[sotmot]

In case you want to have the table centered, use <center>, followed by a new line, table, followed by a new line, </center>.

[Luis Ferrao]

I can't put my finger on why but I love this answer

[Omar YAYA]

Given the convenience, I think this should be the accepted answer.

[mostsignificant]

@zeeshankhan you can use the Liquid filter markdownify in the include as described here: talk.jekyllrb.com/t/rendering-markdown-inside-an-html-includ‌​e/…

[Matt Popovich]

This works, but not for images that you have aligned to the right or left, Ex: ![](path_to_image){: width="400" .right} *image_caption* Anyone have a fix for this?

[kram08980]

This does not work properly, since <em> can be the immediate html element after an <img> inside a paragraph. I had the same idea than you but it doesn't work unfortunately: We notice that *zero* (![Maya digit zero](0.png)) looks very different from any other digits. *zero* is definitely a special case. Creates: <p> We notice that <img src="0.png" alt="Maya digit zero"> looks very different from any other digits. <em>zero</em> is definitely a special case. </p> So, can't use it for all cases.