Adding figures with captions to images in markdown with eleventy
Problem
Markdown is really flexible for writing text, but it's support for images is quite simplistic.
Standard images in markdown

outputs:
<img src="http://placekitten.com/400/300" alt="A kitten">
e.g.
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

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:
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!
Was this useful? → Share it on twitter