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?

Answer 1

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.

Answer 2

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:

Answer 3

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

Answer 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.

Answer 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: lightgrey;

Comes out looking good!

Answer 6

There are two semantically correct solutions to this question:

1. Using a plugin
2. 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)

Answer 7

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.

Answer 8

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*

Answer 9

<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.

Answer 10

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 |

Answer 11

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.

Answer 12

This option might seem complicated on the surface, but it is not at all and solves other problems that the Jekyll markdown renderer (Kramdown) has. Basically this option changes the renderer for one made with python that is expandable, allowing you to instally extensions (there are a ton, markdown-captions for example) and expand it (it has an extension API).

1. The first step is to define a custom markdown processor. You will have to add markdown: CustomProcessor to the _config.yml.

2. Then, we have to create the CustomProcessor. Create a folder called _plugins and add a file called MyConverter.rb with this content:

class Jekyll::Converters::Markdown::CustomProcessor

    def initialize(config)

    end

    def matches(ext)
        ext =~ /^\.(md|markdown)$/i
    end

    def output_ext(ext)
        ".html"
    end

    def convert(content)

      puts "EXECUTED"

      md_path = "./_plugins/temp/temp.md"
      html_path = "./_plugins/temp/temp.html"
      
      File.write(md_path, content, mode: "w")
      system("python ./_plugins/MyConverter.py")

      content = File.read(html_path)
      content
    end
end

You will also need to create a folder temp inside plugins.

All that code does is to write all the content of the file we are processing to temp.md, call a python script, wait until it finishes, read temp.html, and return it as the output of the converter.

3. Now it is time to create our converter in python. I have choosen to use Python-Markdown. It is easy to use and has a ton of extensions. To use the converter we have to create a file called MyConverter.py inside the _plugins folder and put this content inside:

import markdown

markdown_extensions = [
    'markdown_captions',
    'def_list',
    'nl2br',
    'tables',
    'codehilite',
    'fenced_code',
    'md_in_html',
    'attr_list'
]

md_file = open("./_plugins/temp/temp.md", "r")
md_string = md_file.read()
md_file.close()

html_string = markdown.markdown(md_string, extensions=markdown_extensions, extension_configs =extension_configs)

html_file = open("./_plugins/temp/temp.html", "w")
html_file.write(html_string)
html_file.close()

That code just loads the extensions, reads temp.md file, converts it to html and writtes it to temp.html. Using all those extensions should generate a similar output to the default jekyll markdown rendere. The only extension that is not bundled with python-markdown is markdown_captions, the one that does the magic. To install the python renderer and the extension you just have to run pip install Markdown markdown-captions.

That should do it, now your markdown is being translated by Python-Markdown. Some html elements my be different now (in my experience just a few) so maybe you have to make small changes in the css.

This is the css that I am using with the camptions:

figure{
  margin: 0px;
}

figcaption { 
  color: gray;
  font-size: 0.8rem;
}

The process tries to be as simple as possible to make it easy to understand and modify. I have described the process as well as I could remember. If anybody has a problem just leave a comment and I will update the answer.

Answer 13

Add the following config in the _config.yml file

# prose.io config
prose:
  rooturl: '_posts'
  media: 'img'
  ignore:
    - 404.html
    - LICENSE
    - feed.xml
    - _config.yml
    - /_layouts
    - /_includes
    - /css
    - /img
    - /js
  metadata:
    _posts:
      - name: "layout"
        field:
          element: "hidden"
          value: "post"
      - name: "title"
        field:
          element: "text"
          label: "Post title"
          placeholder: "Title"
          alterable: true
      - name: "subtitle"
        field:
          element: "textarea"
          label: "Subtitle"
          placeholder: "A description of your post."
          alterable: true
      - name: "date"
        field:
          element: "text"
          label: "Date"
          help: "Enter date of post."
          placeholder: "yyyy-mm-dd"
          alterable: true
      - name: "image"
        field:
          element: "text"
          label: "Image"
          help: "Add a thumbnail image to your post."
          placeholder: "Thumbnail"
          alterable: true
      - name: "published"
        field:
          element: "checkbox"
          label: "Publish"
          help: "Check to publish post, uncheck to hide."

Answer 14

You can use this javascript that automatically generates a figcaption from the image's alt.

You can add some css to make the bottom text look more realistic.

The same applies to markdown. Whatever text you put ![HERE]() appears below the image.

var images = document.getElementsByTagName("img");
for (var i = 0; i < images.length; i++) {
    var altText = images[i].getAttribute("alt");
    var figcaption = document.createElement("figcaption");
    figcaption.innerHTML = altText;
    images[i].insertAdjacentElement("afterend", figcaption);
}

var images = document.getElementsByTagName("img");
for (var i = 0; i < images.length; i++) {
    var altText = images[i].getAttribute("alt");
    var figcaption = document.createElement("figcaption");
    figcaption.innerHTML = altText;
    images[i].insertAdjacentElement("afterend", figcaption);
}

<img src="https://www.w3schools.com/tags/img_girl.jpg" alt="Girl in a jacket">