Link to main pageMain page 🏡

How to use image title in Gatsby Markdown

With the gatsby-remark-images plugin
Posted on 2020-05-07
5 mins read

Table of contents


First of all, you should add the showCaptions property to your gatsby-remark-images plugin, as it mentioned in docs:

      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
            resolve: "gatsby-remark-images",
            options: {
              maxWidth: 1440,
              linkImagesToOriginal: true,
              showCaptions: ['title'],              markdownCaptions: true            },

As a key's value you should pass an array that represents which image attribute should be used as a caption. Attributes are taken by the order that is set in this array.

If you pass ['title', 'alt'] then Gatsby plugin will look for the title first and if there is no such attribute it will search for an alt tag.

If you want images only with a title tag to have caption text under it you should pass an ['title'] array.

By passing markdownCaptions: true property to plugin's options you are telling it to parse caption text as a markdown instead of raw text.


You are ready to go now. Just pass the title text in double quotes as a second argument to markdown image element:

![image-alt](image-url "(markdown) title")

For example:

![closed](../images/posts/1/ross-stone-G6dbyxMR9pA-unsplash.jpg "Photo by [Ross Stone]( on [Unsplash](")

As a result you'll get something like this:


Photo by Ross Stone on Unsplash

Possible pitfalls

If you have an error like this:

UNHANDLED REJECTION Cannot read property 'contentDigest' of undefined

  TypeError: Cannot read property 'contentDigest' of undefined

  - extend-node-type.js:57 htmlCacheKey

  - extend-node-type.js:337 Object.getHTML [as generateHTML]

  - index.js:150 getImageCaption

  - index.js:306 _callee$

you should update your Gatsby plugins:

npm up gatsby-transformer-remark gatsby-remark-images
npm audit fix

This is a bug and it was fixed around november-december 2019.

Styling 💅

By default, Gatsby image title has no proper CSS styling.

In order to make your title centered and smaller in size you can add to your CSS styles this properties:

.gatsby-resp-image-figcaption {
    font-size: $base-font-size*0.6; // $base-font-size - font size SCSS variable
    text-align: center;

And if your images with title have borders in front of them, this properties can fix it:

figure {
    margin-inline-start: 0px;
    margin-inline-end: 0px;