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

User · Answer

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)

User · Answer

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

User · Answer

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    lt figure class  image  gt     lt img src     include url     alt     include description     gt     lt figcaption gt    include description    lt  figcaption gt   lt  figure gt    And then display the image from your markdown with      include image html url   images my-cat jpg  description  My cat  Robert Downey Jr

User · Answer

lt p align  center  gt     lt img alt  img-name  src   path image-name png  width  300  gt     lt br gt       lt em gt caption lt  em gt   lt  p gt    That is the basic caption use  Not necessary to use an extra plugin

User · Answer

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    lt p gt       lt img src  path to image  alt gt       lt em gt image caption lt  em gt   lt  p gt    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    lt p gt       lt img src  path to image  alt gt   lt  p gt   lt p gt       lt em gt image caption lt  em gt   lt  p gt    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

User · Answer

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

User · Answer

For Kramdown  you can use   refdef  style  quot text-align  center  quot   to align center   refdef  style  quot text-align  center  quot     example  https   upload wikimedia org wikipedia en a a9 Example jpg    width  quot 50  quot   shadow     refdef    refdef  style  quot text-align  center  quot    Fig 1  This is an example image   Source  https   upload wikimedia org wikipedia en a a9 Example jpg      refdef

User · Answer

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      lt img src    alt    style  width  400px    gt      My Caption

User · Answer

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

User · Answer

The correct HTML to use for images with captions  is  lt figure gt  with  lt figcaption gt    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      lt figure gt     lt img src    site url   assets image jpg  alt  my alt text   gt     lt figcaption gt This is my caption text  lt  figcaption gt   lt  figure gt   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

User · Answer

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  lt img gt  markdown     description  https   img jpg  description      Image      description

[github] Using an image caption in Markdown Jekyll

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

Examples related to github

Examples related to markdown

Examples related to jekyll

[github] Using an image caption in Markdown Jekyll

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

Examples related to github

Examples related to markdown

Examples related to jekyll

1.1. Install `jekyll-figure`

1.2. Use `jekyll-figure`