I’d like to start a discussion regarding the serialization of attributes along images on Markdown.
As a reminder, the standard syntax for images in Markdown is: .
For XWiki, ![[alt text|attachment_reference.png]] exists as well, for internal image attachments.
In both case, it is not possible to add additional attributes, limiting the support for:
image alignment
image size
caption
Therefore, I’d like to propose a syntax for image attribute to make it possible to support this feature.
Note that in the context of Cristal, we’ll need to make the effort to mark for each feature if the current backend supports it.
Meaning that we could turn the flag to true for the XWiki backend once Loading..., Loading..., or Loading... are fixed.
Option A: curly brackets attributes
The idea is to place the attributes right after the image, between curly brackers:
As long as a new syntax version (1.3 I guess) is introduced to have this support and existing markdown content (associated to the previous versions, like 1.2) still have the current behavior, it should be fine IMO.
I’ve taken a quick look and I found the link attributes extension from Pandoc. There is another extension by kramdown. According to this discussion, this also works with Jekyll. I think it would make sense to implement one of these existing extensions, I would probably go with the second one. Did you check if the Markdown parser we use supports any of these extensions?
I think it is not 100% clear how image sizes should be represented. See also XWIKI-19976. I think there is the idea that image display sizes should be rendered as CSS while the width and height attributes should represent the intrinsic size of the supplied image file. Therefore, having a separate way to specify image sizes outside of HTML attributes could be interesting.
That said, I think I would go with the most widely supported attribute syntax in order to ensure that the content can also be parsed with external tools and to make it easier to use different parser libraries in XWiki/Cristal.
As a general rule, +1 to review existing syntaxes, to review what flexmark-java supports too, and to pick the most “standard” solution if there’s one.
Note that I’m not 100% sure we need a new syntax since it’s already possible using HTML and HTML is part of the MD syntax. MD is meant to use HTML and it doesn’t support tons of stuff without HTML.
What would need to be supported at the XWiki Markdown extension level is the ability to convert from the image syntax to the HTML syntax when image properties are added and back to the image syntax when the HTML syntax used can be converted back.
Almost all existing issues in the MD jira project are about such problems where there’s no specific syntax representation in MD (you have to use HTML).