Add image captions in Jekyll without a plugin

Markdown images do not provide a built-in way to add captions. In Jekyll, a small include solves that without adding a plugin, so it also works on GitHub Pages.

Create _includes/image.html:

<figure class="image">
  <img src="{{ include.url }}" alt="{{ include.description }}">
  <figcaption>{{ include.description }}</figcaption>
</figure>

The <figure> and <figcaption> elements keep the image and its caption connected semantically.

Use the include from a Markdown post like this:

{% include image.html url="/images/bird.jpg" description="Bird" %}

The description value is used for both the alternative text and the visible caption. That is fine when both should say the same thing. If you need a more detailed alt description, add a separate alt parameter to the include instead of forcing one piece of text to do two jobs.

← Back to all articles