hugo org image title

One of the differences between using markdown and org-mode markup for writing Hugo pages is how you set the alternative text and title of an image.

In markdown, you would write it as

![alt text](dummy-image.png "Image Title")

Where in org-mode, typically you would use a caption like this

#+CAPTION: Image Title
[[file:dummy-image.png]]

and that would be the end of it. However in Hugo, if we use that format, we end up with this

dummy-image.png
Image Title

with the following HTML

<figure>
  <img src="dummy-image.png" alt="dummy-image.png" title="dummy-image.png">
  <figcaption>
    Image Title
  </figcaption>
</figure>

With the caption being put into a figure, and the image's alt text and title being set to the URL of the image, which isn't very helpful for people using screen readers, or if the image fails to load. It also takes up room with text we normally wouldn't be showing unless the image was being hovered over.

If we give the org-mode link a title, it just turns into a regular link to an image instead of embedding it

[[file:dummy-image.png][Image Title]]

Image Title

resulting in this HTML

<a href="dummy-image.png">Image Title</a>

The way around this is to use the #+ATTR_HTML element in org-mode. You use it in the format of #+ATTR_HTML: :<attr> <value>. So to add a title and alt text to an image, you would add

#+ATTR_HTML: :alt alt text
#+ATTR_HTML: :title Image Title

Above the embedded image, resulting in

#+ATTR_HTML: :alt alt text
#+ATTR_HTML: :title Image Title
[[file:dummy-image.png]]

Which finally outputs what we want

alt text

giving us this HTML

<img src="dummy-image.png" alt="alt text" title="Image Title">