Change image dimensions in markdown
Final decision, we're going with the syntax laid out in https://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md, which is written by the author of CommonMark.
For example,
{width=75%}
creates the html
<img src="image.jpg" width="75%">
Only height
and width
are supported - there is no support for classes or other other attributes.
See Markdown attribute syntax for images (!104904 - merged) for the implementation.
Original description
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:
{:.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.
Release Notes
Before this release, there were no controls for changing the size of images rendered within markdown text areas. This often led to unwieldy images with no control over how much space they took up within descriptions and comments. You can now set the width and height of how images will be rendered directly within markdown. Sizes can be set based on pixels or percentages.
https://docs.gitlab.com/ee/user/markdown.html#change-the-image-dimensions