← 11ty notes

Adding figures with captions to images in markdown with eleventy

• 🍿 3 min. read

Problem

Markdown is really flexible for writing text, but it's support for images is quite simplistic.

Standard images in markdown

![A kitten](http://placekitten.com/400/300)

outputs:

<img src="http://placekitten.com/400/300" alt="A kitten">

e.g.
A kitten

However I want to generate something more useful to readers, i.e. images with nice captions like:

<figure>
<img src="http://placekitten.com/400/300" alt="A kitten">
<figcaption>Chesney the Kitten attempts a giant leap<figcaption>
<figure>

Now you can do this by just including HTML in your markdown, but this gets boring fast, and I wanted a single markdown tag to do this with.

Solution

Use the markdown-it plugin markdown-it-image-figures.

Full plugin docs are here, but if you want to output simple images with alt tags and title like:

<figure>
<img src="fig.png" alt="This is an alt">
<figcaption>This is a caption</figcaption>
</figure>

you need the following config alongside your markdown library configuration in your .eleventy.js file:

let markdownIt = require("markdown-it");
let options = {
// whatever options you have set for the library here
};
let mdfigcaption = require('markdown-it-image-figures');
let figoptions = {
figcaption: true
};

const mdLib = markdownIt(options).use(mdfigcaption, figoptions);

module.exports = function (config) {
//other config here

config.setLibrary("md", mdLib);
}

N.B. the figcaption option sets the plugin to use a specified image title as the fig caption.

Usage

![A Kitten](http://placekitten.com/400/300 "Chesney the Kitten attempts a giant leap")

outputs the following HTML

<figure>
<img src="http://placekitten.com/400/300" alt="A kitten">
<figcaption>Chesney the Kitten attempts a giant leap<figcaption>
<figure>

which renders with a bit of styling like:

A Kitten
Chesney the Kitten attempts a giant leap

Gotchas to watch out for

  • you have to pass the figcaption options in with the plugin, not in with the main libary options.
  • leave a blank line above the markdown image tag otherwise it doesn't seem to render properly.
  • You’re only allowed one module.exports in your configuration file, so make sure you only add the config to you tour existing one!

Check out other things I've written tagged: eleventy

← 11ty notes