Markdown Image Titles and Alt Text
Tags: markdown
Published: 2019-08-26 14:28:00

---
title: Markdown Image Titles and Alt Text
published: true
tags: markdown
canonical_url: https://stephencharlesweiss.com//2019-08-22/markdown-images-alt-text-and-title/
---

I continue to be impressed by the simplicity and power of Markdown.

Today, while exploring the API for Gatsby’s Remark Images, I noticed the option: `showCaptions`. <sup>1</sup>

> Add a caption to each image with the contents of the title attribute, when this is not empty. If the title attribute is empty but the alt attribute is not, it will be used instead. Set this option to true to enable this behavior. You can also pass an array instead to specify which value should be used for the caption — for example, passing `[‘alt’, ‘title’]` would use the alt attribute first, and then the title. When this is set to `true` it is the same as passing `[‘title’, ‘alt’]`. If you just want to use the title (and omit captions for images that have alt attributes but no title), pass `[‘title’]`.

It was the inclusion of “Title” that caught me off guard. I’d never seen / used that before.

I’d always imported my images as: `![Alt](/path/to/img.jpg)`.

It turns out, however, that there’s a second argument that can be passed in _after_ the path: the title.<sup>2</sup>

```markdown
![Alt](/path/to/img.jpg “image title”)
```

## <svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>Example

I wanted to see what this would look like in a blog post - so, I tried adding the following image in a Gatsby blog: `![hello!](~./images/adam-solomon-hello.jpg~ "adam solomon's hello”)`.

As expected, we see the `alt` and `title` properties present on the `img` tag in the HTML: ![](&&&SFLOCALFILEPATH&&&Screen%20Shot%202019-08-19%20at%206.17.19%20AM.png)

``` html
<img class="gatsby-resp-image-image" src="/static/0006f3a2fe907f8d0b63c65e51983802/a111b/adam-solomon-hello.jpg" alt="hello!" title="adam solomon's hello">
```

Here’s the relevant `gatsby-config` — the images are a plugin as a part of the options for `gatsby-plugin-mdx` — which is what I’m using to compile the Markdown into HTML.

``` javascript
module.exports = {
  plugins: [
    ‘gatsby-plugin-sharp’,
    ‘gatsby-transformer-sharp’,
    {
      resolve: ‘gatsby-plugin-mdx’,
      options: {
        extensions: [‘.mdx’, ‘.md’],
        defaultLayouts: {
          default: require.resolve(‘./src/components/layout.js’),
        },
        gatsbyRemarkPlugins: [
          {
            resolve: ‘gatsby-remark-images’,
            options: {
              markdownCaptions: true,
              linkImagesToOriginal: false,
              showCaptions: [‘title’, ‘alt’],
              withWebp: true,
              tracedSVG: { color: ‘#F00’, turnPolicy: ‘TURNPOLICY_MAJORITY’ },
            },
          },
        ],
      },
    },
  ],
};
```

Note: The `showCaptions` option will only show either Title _or_ Alt in the body of the document. Not both. Though, both are present in the HTML for screen readers.

For additional styling, I also found this blog post by xaprb informative.<sup>3</sup>

# <svg aria-hidden="true" focusable="false" height="16" version="1.1" viewbox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>Resources

- <sup>1</sup> [Remark Images | Gatsby](https://www.gatsbyjs.org/packages/gatsby-remark-images/)
- <sup>2</sup> [Markdown Syntax Documentation | Daring Fireball](https://daringfireball.net/projects/markdown/syntax#img)
- <sup>3</sup> [How to Style Images With Markdown](https://www.xaprb.com/blog/how-to-style-images-with-markdown/)