Markdown syntax for images that supports sizing and captions

[kellyjosephprice]

Looks good. A bit bummed about having to move image serialization back to the magic block format… any thoughts on a way to manage captions and sizing in RDMD-flavored syntax?

Originally posted by @rafegoldberg in #377 (review)

Commonmark Dicussions Forum

[kellyjosephprice]

One idea is to use position data:

![Alt text](/image-url "title" "sizing" "caption")

Or, named attributes:

![Alt text](/image-url "title" sizing="..." caption="...")

I've seen somewhere a syntax for adding arbitrary attributes to markdown elements:

![Alt text](/image-url){: title="..." sizing="..." caption="..." }

---

I'm not a fan of position attributes, having to know the order is not friendly. And I think it's a little antithetical to the markdown philosophy to use named attributes at all. It'd be nice if there was a shorthand for it.

[kellyjosephprice]

This comment has some pretty interesting takes on how to represent captions in a block shorthand. I particularly like the ones that have a prefix for the caption:

![alt](/url)
: caption

![alt](/url)
! caption

![alt](/url)
-- caption

[rafegoldberg]

Thanks for opening this @kellyjosephprice! I agree that positional attributes are a pain, and I'm not a big fan of that final arbitrary attribute syntax either. I think I'd say some kind of named attributes are the simplest, and most markdown like, so I'd vote moving in that direction!

[kellyjosephprice]

A simpler method would be to treat a block immediately following an image as a caption, as from this parent thread:

![](/image-url)
caption?

[thenaomiday]

@kellyjosephprice @rafegoldberg I'm re-upping this thread (as per a conversation with Kelly) to make a decision on image markdown syntax so I can update images to always use markdown syntax (the current block syntax breaks tables in a bad way, so taking the chance to just update this).

I'm inclined to go with named attributes, despite that they are somewhat un-markdown-like:
![Alt text](/image-url "title" width="..." caption="...")

Are we cool with this approach? Speak now or (at least temporarily) hold your peace!

[martin-cod]

Do html tags work for this?

Falavored markdown + centered caption using html tag <p>

![Image Alt Text](https://files.readme.io/4d1f928-_eafcc389-ea5a-40e2-9539-37ddf358d3d4.jpeg "Image Title")  
_<p style="text-align: center;">Image Caption</p>_

Alternative image caption syntax:

<figure>
    <img src="https://files.readme.io/4d1f928-_eafcc389-ea5a-40e2-9539-37ddf358d3d4.jpeg"
         alt="Image Alt Text"
         title="Image Title">
    <figcaption>Alternative Image Caption</figcaption>
</figure>

Image center alignment

<div style="text-align: center;">
    <img src="https://files.readme.io/0f9be14-_eafcc389-ea5a-40e2-9539-37ddf358d3d4_200x200.jpg">
</div>

and image right alignment.

<div>
    <img align="right" src="https://files.readme.io/0f9be14-_eafcc389-ea5a-40e2-9539-37ddf358d3d4_200x200.jpg">
    <img align="right" src="https://files.readme.io/0f9be14-_eafcc389-ea5a-40e2-9539-37ddf358d3d4_200x200.jpg">
    <img align="right" src="https://files.readme.io/0f9be14-_eafcc389-ea5a-40e2-9539-37ddf358d3d4_200x200.jpg">
    <div style="clear:both"></div>
</div>

I've noted, that style attribute is not supported in GitHub Markdown representation.