Skip to content

Change image dimensions in markdown

Final decision, we're going with the syntax laid out in http://github.com/jgm/commonmark-hs/blob/master/commonmark-extensions/test/attributes.md, which is written by the author of CommonMark.

For example,

![](image.jpg){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:

![GitLab Logo](http://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: http://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"}

Maruku / Kramdown:

{:ref-name: #myid .my-class}

Markua:

{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 and height 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 the pandoc 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.

http://docs.gitlab.com/ee/user/markdown.html#change-the-image-dimensions

Edited by Gabe Weaver