Markdown attribute syntax for images
This is a proposal to add support for an attribute syntax to our flavor of markdown. This would allow some additional control over styling of elements.
For example, there have been many requests to allow for the sizing of images, or adding a border around an image
We render all GitLab markdown using CommonMark. While there are on-going discussions in the forum, CommonMark currently does not support any type of attribute syntax or image sizing control.
I believe we should start an initial discussion/implementation, supported only for images, that allow a whitelisted CSS class to be specified:
![GitLab Logo](https://gitlab.com/gitlab-org/gitlab-ce/uploads/871c348e9df9d3b4f006b98bda90e4b4/images.png){:.thumbnail.bordered}
We can then iterate on this for possibly adding support for width=
and height=
One of the difficulties is in choosing the format of the syntax. There is currently no consensus in CommonMark as to which is the best format: https://talk.commonmark.org/t/consistent-attribute-syntax/272/123
Keep in mind, there’s already some variation (or is it fragmentation?) in attribute syntax among different Markdown flavors and other writing formats like Markua. For example…
Pandoc / PHP Markdown Extra / Earlier version of CommonMark spec:
{#myId .myClass key=val key2="val 2"}
{:ref-name: #myid .my-class}
{key_one: value1, key_two: value_two, key_three: "value three!", key_four: true, key_five: 0, key_six: 3.14}
Considerations
-
Security
One of the problems we have to consider though is security. Allowing arbitrary attributes to be specified can wreak all sorts of havoc. We are pretty aggressive right now about stripping out styles from user input. So any support for classes/styles/attributes would probably need to be whitelisted:
width
andheight
attributes for images,.border
for a simple border maybe, etc -
Syntax incompatibility
No matter what syntax we choose, there is a possibility that CommonMark eventually makes a decision and we chose wrong. For example if we choose the
kramdown
style and they go with thepandoc
style, or vice versa. This could mean that we end up having to perform some type of migration, or support both styles ad infinitum - neither is desirable.Choosing something that seems to be the common direction might help mitigate that, but the possibility still remains.