#+TITLE: How To Set An Image Title In Hugo Using Org-Mode Markup
#+DATE: 2020-06-24T19:50:03-04:00
#+DRAFT: true
#+DESCRIPTION: How to set the title or alt text of an image in hugo using org-mode markup
#+TAGS[]: hugo org-mode
#+KEYWORDS[]: hugo org-mode
#+SLUG:
#+SUMMARY:

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
#+BEGIN_SRC
![alt text](dummy-image.png "Image Title")
#+END_SRC

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

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

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

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

with the following HTML

#+BEGIN_SRC html
<figure>
  <img src="dummy-image.png" alt="dummy-image.png" title="dummy-image.png">
  <figcaption>
    Image Title
  </figcaption>
</figure>
#+END_SRC

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

#+BEGIN_SRC org
[[file:dummy-image.png][Image Title]]
#+END_SRC

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

resulting in this HTML

#+BEGIN_SRC html
<a href="dummy-image.png">Image Title</a>
#+END_SRC


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

#+BEGIN_SRC org
#+ATTR_HTML: :alt alt text
#+ATTR_HTML: :title Image Title
#+END_SRC

Above the embedded image, resulting in

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

Which finally outputs what we want

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

giving us this HTML

#+BEGIN_SRC html
<img src="dummy-image.png" alt="alt text" title="Image Title">
#+END_SRC