How to put a caption on an html-export'ed image?

Question

I want to export two images side-by-side, and this works:

#+begin_export html
<img style="width:45%" src="test-images/a-3.jpg" /> <img style="width:45%" src="figs/a-3-boxes.png" />
#+end_export

Meanwhile, if I want to put a caption on a single image, this works:

#+CAPTION: Original vs. Boxed
[[file:test-images/a-3.jpg]]

But adding a caption to the "two images" version results in no caption at all in the exported .html file:

#+CAPTION: Original vs. Boxed
#+begin_export html
<img style="width:45%" src="test-images/a-3.jpg" /> <img style="width:45%" src="figs/a-3-boxes.png" />
#+end_export

How can I have both:

1. two images side-by-side
2. a single caption (which spans both images) that reads Figure 1: Original vs. Boxed

Thanks!

[edit]

I found this StackOverflow answer which suggests to just put a caption on top of the html export, but when I tried this, there was no caption.

Answer 1

As a first approximation, you can use a table:

#+CAPTION: Original vs. Boxed
| [[./test-images/ex1.jpg]] | [[./test-images/ex2.jpg]] |

The caption is above, it is labeled "Table 1", but both of these can be fixed: the first by setting org-html-table-caption-above to nil, the second with an export filter.

EDIT: here's a complete example with the added filters:

* foo

#+CAPTION: Original vs. Boxed
| [[./test-images/ex1.jpg]] | [[./test-images/ex2.jpg]] |


* Code                                                     :noexport:

#+name: set
#+begin_src elisp
  (defun my/html-filter-image-width(text backend info)
    (when (org-export-derived-backend-p backend 'html)
      (replace-regexp-in-string "<img src" "<img width=\"500px\" src" text)))

  (defun my/html-filter-fix-caption(text backend info)
    (when (org-export-derived-backend-p backend 'html)
      (replace-regexp-in-string ">Table " ">Figure " text)))

  (add-to-list 'org-export-filter-link-functions #'my/html-filter-image-width)
  (add-to-list 'org-export-filter-table-functions #'my/html-filter-fix-caption)

  (setq org-html-table-caption-above nil)
#+end_src


#+name: reset
#+begin_src elisp
  (setq org-export-filter-link-functions (delete #'my/html-filter-image-width org-export-filter-link-functions))
  (setq org-export-filter-table-functions (delete #'my/html-filter-fix-caption org-export-filter-table-functions))
  (setq org-html-table-caption-above t)
#+end_src

You have to watch out that the regexps don't match unintended portions of the buffer.

I like putting code in code blocks in a special Code section that's marked noexport, at the end of the file , but there are other ways of doing it (e.g. you can define the functions in your init file, but set the variables through the file local variables mechanism.) When you open the file, do C-c C-c on the first code block to set up everything, then C-c C-e h h to export. Note that the variables are global, so you might want to run the second code block before you kill the buffer to reset the values to what they were before (assuming that you have not changed the default value of org-html-table-caption-above which is t).