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?

Andrew Wei · Answer 1 · 2015-05-21T06:55:52.640

326

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.

edited May 21 '15 at 06:55

answered May 21 '15 at 06:45

Andrew Wei

3,717
2
14
6

4

Awesome! No need to memorize some stupid jekyll syntax :) – Corstian Boerman Jul 31 '15 at 12:32
2

I'm a big fan of this – ahwillia Sep 10 '15 at 04:26
Thank you! Was just searching for that – Michal Gruca Apr 05 '17 at 10:22
1

Hi there! I am not quite sure where and how to put the CSS part...it would be really great if anyone could help. – ChriiSchee Apr 10 '19 at 13:50
2

@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 `` 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` – Jan Zavrel Sep 15 '19 at 04:01
It's a shame that CSS doesn't allow you to go up the chain, so you could target the
tag here based on it having an and an . Something like `img+em < p {rules}`.
– Codemonkey Oct 27 '20 at 07:13
I can't put my finger on why but I love this answer – Luis Ferrao Dec 10 '20 at 14:15
Given the convenience, I think this should be the accepted answer. – Omar Yaya May 23 '21 at 00:33

score 154 · Answer 2 · answered Jul 19 '17 at 12:52

154

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:

answered Jul 19 '17 at 12:52

Bilal Gultekin

3,631
3
20
27

21

This answer is the best one.. Using pure markdown and getting what you need. Thanks! – Kadam Parikh Jan 25 '20 at 06:51
Sort of offtopic, but this also works in Jupyter Notebooks. – paulochf Feb 01 '20 at 20:38
It reduced the width from 100% for me. How do I widen it? – Abhay Hegde Jun 16 '20 at 19:31
1

In case you want to have the table centered, use , followed by a new line, table, followed by a new line, . – sotmot Dec 03 '20 at 10:57

score 140 · Accepted Answer · edited Feb 09 '19 at 14:11

140

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." %}

edited Feb 09 '19 at 14:11

Andrew Dunning

103
4

answered Oct 14 '13 at 12:30

IQAndreas

7,014
4
36
63

1

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 }}...`. – orschiro Oct 14 '13 at 19:48
2

Ah, right, that is a variable added in [Octopress](http://octopress.org/). I edited it out, so the sample code just uses a relative URL to the image. – IQAndreas Oct 15 '13 at 01:31
3

Jekyll now includes a `site.url` variable. – Roy Tinker Nov 14 '14 at 00:22
21

A better markup would be: `
{{ include.description }}
` – edmundo Aug 06 '15 at 01:24
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? – edmundo Aug 06 '15 at 01:29
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). – cregox Aug 28 '20 at 12:39
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 – zeeshan khan Nov 01 '20 at 15:50

bryanbraun · Answer 4 · 2018-11-12T18:52:30.277

78

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.

edited Nov 12 '18 at 18:52

answered Jul 06 '17 at 14:32

bryanbraun

2,525
1
22
33

7

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. ;-) – sudo make install Jul 19 '17 at 22:12
I agree. However it seems not to be supported by Bitbucket yet. A pitty. – Boriel Nov 02 '17 at 11:07
1

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. – Seanba Sep 11 '18 at 16:26
1

Thanks a lot, I am new to jekyll and didn't know markdown can be used with html. – Sambo Kim Feb 20 '20 at 04:59

score 9 · Answer 5 · edited May 23 '17 at 11:33

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!

Robin Métral · Answer 6 · 2018-08-17T05:01:05.327

There are two semantically correct solutions to this question:

Using a plugin
Creating a custom include

1. Using a plugin

I've tried a couple of plugins doing this and my favourite is jekyll-figure.

1.1. Install `jekyll-figure`

One way to install jekyll-figure is to add gem "jekyll-figure" to your Gemfile in your plugins group.

Then run bundle install from your terminal window.

1.2. Use `jekyll-figure`

Simply wrap your markdown in {% figure %} and {% endfigure %} tags.

You caption goes in the opening {% figure %} tag, and you can even style it with markdown!

Example:

{% figure caption:"Le logo de **Jekyll** et son clin d'oeil à Robert Louis Stevenson" %}
    ![Le logo de Jekyll](/assets/images/2018-08-07-jekyll-logo.png)
{% endfigure %}

1.3. Style it

Now that your images and captions are semantically correct, you can apply CSS as you wish to:

figure (for both image and caption)
figure img (for image only)
figcaption (for caption only)

2. Creating a custom include

You'll need to create an image.html file in your _includes folder, and include it using Liquid in Markdown.

2.1. Create _includes/image.html

Create the image.html document in your _includes folder :

<!-- _includes/image.html -->
<figure>
    {% if include.url %}
    <a href="{{ include.url }}">
    {% endif %}
    <img
        {% if include.srcabs %}
            src="{{ include.srcabs }}"
        {% else %}
            src="{{ site.baseurl }}/assets/images/{{ include.src }}"
        {% endif %}
    alt="{{ include.alt }}">
    {% if include.url %}
    </a>
    {% endif %}
    {% if include.caption %}
        <figcaption>{{ include.caption }}</figcaption>
    {% endif %}
</figure>

2.2. In Markdown, include an image using Liquid

An image in /assets/images with a caption:

This is [Jekyll](https://jekyllrb.com)'s logo :

{% include image.html
    src="jekyll-logo.png" <!-- image filename (placed in /assets/images) -->
    alt="Jekyll's logo" <!-- alt text -->
    caption="This is Jekyll's logo, featuring Dr. Jekyll's serum!" <!-- Caption -->
%}

An (external) image using an absolute URL: (change src="" to srcabs="")

This is [Jekyll](https://jekyllrb.com)'s logo :

{% include image.html
    srcabs="https://jekyllrb.com/img/logo-2x.png" <!-- absolute URL to image file -->
    alt="Jekyll's logo" <!-- alt text -->
    caption="This is Jekyll's logo, featuring Dr. Jekyll's serum!" <!-- Caption -->
%}

A clickable image: (add url="" argument)

This is [Jekyll](https://jekyllrb.com)'s logo :

{% include image.html
    src="https://jekyllrb.com/img/logo-2x.png" <!-- absolute URL to image file -->
    url="https://jekyllrb.com" <!-- destination url -->
    alt="Jekyll's logo" <!-- alt text -->
    caption="This is Jekyll's logo, featuring Dr. Jekyll's serum!" <!-- Caption -->
%}

An image without a caption:

This is [Jekyll](https://jekyllrb.com)'s logo :

{% include image.html
    src="https://jekyllrb.com/img/logo-2x.png" <!-- absolute URL to image file -->
    alt="Jekyll's logo" <!-- alt text -->
%}

2.3. Style it

Now that your images and captions are semantically correct, you can apply CSS as you wish to:

figure (for both image and caption)
figure img (for image only)
figcaption (for caption only)

Just for completeness, if you want to use jekyll-figure you will have to add jekyll-figure to plugins in your _config.yml — Aleix Sanchis, Mar 30 '20 at 00:59

score 3 · Answer 7 · edited Jan 08 '17 at 20:00

3

You can try to use pandoc as your converter. Here's a jekyll plugin to implement this. Pandoc will be able to add a figure caption the same as your alt attribute automatically.

But you have to push the compiled site because github doesn't allow plugins in Github pages for security.

edited Jan 08 '17 at 20:00

Ahmad

58,947
17
107
133

answered Oct 13 '13 at 08:32

Chongxu Ren

1,497
2
13
14

Thanks. So markdown alone is not capable of creating captions? – orschiro Oct 13 '13 at 08:54
I believe it depends on the converter you use, however, markdown standard doesn't support adding captions. – Chongxu Ren Oct 13 '13 at 09:00

score 3 · Answer 8 · answered Jan 07 '18 at 12:21

Andrew's @andrew-wei answer works great. You can also chain a few together, depending on what you are trying to do. This, for example, gets you an image with alt, title and caption with a line break and bold and italics in different parts of the caption:

img + br + strong {margin-top: 5px; margin-bottom: 7px; font-style:italic; font-size: 12px; }
img + br + strong + em {margin-top: 5px; margin-bottom: 7px; font-size: 12px; font-style:italic;}

With the following <img> markdown:

![description](https://img.jpg "description")
***Image:*** *description*

score 2 · Answer 9 · answered Feb 21 '20 at 19:52

2

<p align="center">
  <img alt="img-name" src="/path/image-name.png" width="300">
  <br>
    <em>caption</em>
</p>

That is the basic caption use. Not necessary to use an extra plugin.

answered Feb 21 '20 at 19:52

Hasan Tezcan

472
2
10

score 0 · Answer 10 · answered Dec 09 '16 at 09:16

Here's the simplest (but not prettiest) solution: make a table around the whole thing. There are obviously scaling issues, and this is why I give my example with the HTML so that you can modify the image size easily. This worked for me.

| <img src="" alt="" style="width: 400px;"/> |
| My Caption |

zeeshan khan · Answer 11 · 2021-03-15T19:43:51.960

For Kramdown, you can use {:refdef: style="text-align: center;"} to align center

{:refdef: style="text-align: center;"}
![example](https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg){: width="50%" .shadow}
{: refdef}
{:refdef: style="text-align: center;"}
*Fig.1: This is an example image. [Source](https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg)*
{: refdef}

You need to add {::options parse_block_html="true" /} at the beginning of the post for this to work.

Using an image caption in Markdown Jekyll

11 Answers11

1. Using a plugin

1.1. Install `jekyll-figure`

1.2. Use `jekyll-figure`

1.3. Style it

2. Creating a custom include

2.1. Create _includes/image.html

2.2. In Markdown, include an image using Liquid

2.3. Style it

Linked

Using an image caption in Markdown Jekyll

11 Answers11

1. Using a plugin

1.1. Install jekyll-figure

1.2. Use jekyll-figure

1.3. Style it

2. Creating a custom include

2.1. Create _includes/image.html

2.2. In Markdown, include an image using Liquid

2.3. Style it

Linked

1.1. Install `jekyll-figure`

1.2. Use `jekyll-figure`