Re: [BUG] ox-md image captions

[Ihor Radchenko <yantar92@posteo.net>]

Max Nikulin <manikulin@gmail.com> writes:

>> Upon further investigation, I have found that our base MD reference we
>> follow in ox-md is defining image syntax as the following:
>> 
>> ![Alt text](/path/to/img.jpg)
>> 
>> ![Alt text](/path/to/img.jpg "Optional title")
>> 
>> https://daringfireball.net/projects/markdown/syntax#img
>> 
>> Therefore, Org mode is doing everything right within the scope of MD
>> specification we follow. Pandoc does not.
>
> My reading of 
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#the_title_attribute 
> is that caption should not be exported as title. Alt text is more 
> "visible" than title, but perhaps caption should be exported as text 
> adjacent to image.

I will provide the linked text at the end of the message for future
reference.

For HTML, I agree that caption should ideally be exported as text adjacent
to image. That's what we actually do in `org-html--wrap-image'.

However, we are talking about MD export.

MD has nothing to do with how Pandoc's "implicit_figures" extension
modifies MD->HTML export. The original MD spec only talks about image
description and image title being exported to "alt" and "title" HTML
attributes.

Currently, Org's image link description will be exported to MD's image
link description and Org's image caption will be exported to MD's image
title. Doing otherwise by default is not entirely consistent.

Of course, the current default will also ignore #+caption altogether
unless the image link has no description. So, we may, in theory, play
around with the default.

On the other hand, by keeping the current default we also keep the
option to combine description and caption if we ever consider altering
our inline image rules during export (`org-export-inline-image-p').

I am still inclined towards keeping the current default, as not every
possible MD export user is doing it to consequently convert the MD to
HTML using Pandoc also having the "implicit_figures" Pandoc's extension
enabled.

We may provide a toggle for this, however. If someone is bothered enough
and sends a patch. Maybe #+ATTR_MD: also option.

----

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#the_title_attribute

    The title attribute is not an acceptable substitute for the alt
    attribute. Additionally, avoid duplicating the alt attribute's value
    in a title attribute declared on the same image. Doing so may cause
    some screen readers to announce the description twice, creating a
    confusing experience.
    
    The title attribute should also not be used as supplemental
    captioning information to accompany an image's alt description. If
    an image needs a caption, use the figure and figcaption elements.
    
    The value of the title attribute is usually presented to the user as
    a tooltip, which appears shortly after the cursor stops moving over
    the image. While this can provide additional information to the
    user, you should not assume that the user will ever see it: the user
    may only have keyboard or touchscreen. If you have information
    that's particularly important or valuable for the user, present it
    inline using one of the methods mentioned above instead of using
    title.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>