Make clearer how typical alt text is affected by inclusion of image resizing/background syntax

[elichad]

The Image syntax section of the docs shows how an image can be resized or used as a background by adding keywords to the image alt text, e.g. ![width:200px](image.jpg).

However, there are no examples of how to include more typical alt text (i.e. a description of the image) along with this syntax. It's not clear from the documentation if these keywords are removed from the alt text when rendering the Markdown, or if they would remain and therefore add noise for a screen reader user. I'd like to see more information provided on this front, to discourage users from misusing the alt text feature as only a formatting tool.

Personally, this almost put me off from using Marp altogether. I always include alt text when writing slides and thought this was just another case of developers overlooking accessibility (which is all too common).

Fortunately, I decided to experiment a bit first, and found that ![width:200px Description of image](image.jpg) will be rendered into HTML as <img src="image.png" alt="Description of image" style="width:200px">. This is a good feature - please make it clearer that it exists! :)

[elichad]

There is a conversation to be had about whether the alt text feature of Markdown should be used for this kind of purpose at all. I think it shouldn't, and the Markdown community should strive to find other ways to handle styling information.

But since this is a functional feature already, and it produces well-styled HTML, I think it's sufficient for now just to document this better.

[yhatt]

If you missed, CommonMark community is discussing about attribute syntax: https://talk.commonmark.org/t/consistent-attribute-syntax/272

Attribute syntax is adopted in some famous Markdown processors (Pandoc, Markdown Extra, etc) but still not majority. If not supported, the command text for attributes would be leaked to the rendering result unnecessary.

Marp makes importance Markdown rendering compatibillity with other editors by adopting CommonMark, so we decided not to adopt the attribute syntax. The current approach is a proven way in Deckset, and it's natural decision considering that Marp was originally designed an open-source and cross-platform version of Deckset.
https://docs.decksetapp.com/English.lproj/Media/01-background-images.html

In GitHub, there is a similar discussion about abusing exist Markdown syntax. It's always hard "chicken or egg" thing about adding helpful features with keeping semantics and no breaking Markdown backward compatibility.

[elichad]

Thanks for sharing all your thoughts and links to where this has been discussed elsewhere. I'm glad to know the issues are at least on your radar, even if it's hard to find a satisfying solution.

[yhatt]

Agree. I currently hate to abuse alternative text for the image in the point of view of accessibility. But it's difficult to overturn the past decision with keeping backward compatibillity of exisiting many Marp documents. And there are few people to discuss about this problem in Marp community, because many users want the convenience of setting about slide appearance. 😓

Removing recognized keywords from the alternative text had mentioned at marp-team/marpit#316 and fixed by marp-team/marpit#318, but there was not docs update in this PR. We are anytime welcome to pull request for updating docs.

In the next-gen Marpit framework, we think that this feature will become opt-in feature (marp-team/marpit#194 (comment)). But in Marp Core, as known as Marp commonly, we might have to keep enabled this feature for getting backward compatibility even if the framework was bumped to the next version.

[yhatt]

The author of fusuma, yet another CLI tool for making Markdown slide, also had implicitly complained about Marp's image syntax (without naming). Translated version:

When I thought about the specifications for creating slides in Markdown, I was most troubled by the fact that md had no expressive power to handle images in css, so I had no choice but to write them in html. However, this would make it difficult for the slide creator to handle the images, and I wanted to avoid putting the property in the alt field because it would not be correct even as an html/md specification. In the first place, it is not an "alt".

— https://twitter.com/about_hiroppy/status/1544453689590423552 (Japanese)

[yhatt]

UPDATE: That has been clarified by the community's contribution to the documentation of Marpit framework: marp-team/marpit#422 by @af3556

The extended features are enabled by including corresponding keywords in the image’s alternative text; the remaining alternative text is rendered as alt text for inline images or the figure caption for background images.

— https://marpit.marp.app/image-syntax