Markdown syntax for clickable images

As a part of a private message discussion, it occurred to me that people here may not know how to create a clickable image link using the Discourse software that runs TidBITS Talk.

This post is for everybody else’s benefit.

For my examples, I am using the xkcd comic from a few days ago: I’m using xkcd because the site’s policies permit sharing comics on blogs and provides easily-accessible URLs for linking and embedding content.

The comic page shows two key URLs:

(Note: When you read this, the above image URL link, when used in the examples below, have been replaced with an internal “upload” URL, because Discourse caches copies of images. If you use these examples, just pretend that those upload:.... URLs are your image’s URL.)

If you just provide the URLs

Discourse automatically expands the URLs into their content. The page URL renders as its title text (as a clickable link): renders as: xkcd: Lightsabers

If you do this with the image link, it renders as the image, but it is not a link to anything. renders as:

Making the image clickable (Markdown style)

Basic Markdown syntax for a clickable image is:

[![alt text](image URL)](link URL)


  • alt text is the “alternate” text that some browsers may display in place of the image. It is most commonly used by text-based browsers and screen readers.
    You can omit the alt text (just use the brackets with no text between them: []) if you want, but you should probably supply something, so those who can’t see the image will have some clue about what is being shown.
  • image URL is a URL to the image that will be displayed
  • link URL is where you will go when you click on the image.

So a clickable link to the above comic might be:


Or if you want to attempt to describe it in the alt text:

[![A surreal comic involving a light saber duel](upload://oFn0UDQ10KkU1TCnTt9CjNApU28.png)](

and it renders as:

A surreal comic involving a light saber duel

Making the image clickable (embedded HTML)

If you prefer, you can also use an HTML IMG tag as the link text for a normal Markdown link:

[<IMG SRC="image URL">](link URL)

So the above clickable link (without alt text) could be presented as:

[<img src="upload://oFn0UDQ10KkU1TCnTt9CjNApU28.png">](

Or if you want to include alt text:

[<img src="upload://oFn0UDQ10KkU1TCnTt9CjNApU28.png" alt="A surreal comic involving a light saber duel">](

and it renders as:

A surreal comic involving a light saber duel

The really cool thing about this syntax is that you can use any HTML properties that an IMG tag supports (limited by what Discourse may filter out). This is great for sites like xkcd which embed additional content in “title” properties, which render as tooltips.

So I can embed those additional properties with something like:

[<img src="upload://oFn0UDQ10KkU1TCnTt9CjNApU28.png" title="A lot of Jedi romances start with this turning into a Lady and the Tramp spaghetti situation." alt="Lightsabers" srcset="// 2x">](

For the above, I copied the entire IMG tag from the original page, only omitting the style= tag, since that tag is tied to the xkcd site’s stylesheet, which is completely different from the TidBITS Talk style sheet.

The above renders as:


Note the tooltip text on this image.


Using this for giving attribution

Many web sites permit linking and embedding content, but they often require attribution. While linking to the content’s page may be enough for some people, it may not be enough for others.

For example, if I want to embed this Wikipedia image: File:QAM16 Demonstration.gif - Wikipedia

The Creative Commons license includes the following requirement:

You are, of course, free to give attribution in any way you believe is appropriate, but here’s one way involving a clickable image to the page where the original image is used, and a small table in order to present where you provide attribution text/links as a caption:

| [![Digital QAM chart](upload://w3Mffg0oJSdPbOWWMAP5j7iAoCr.gif)]( |
| :--: |
| Image credit: Chris Watts, [Wikimedia Commons](  [CC BY-SA 3.0]( |

renders as:

Digital QAM chart
Image credit: Chris Watts, Wikimedia Commons. CC BY-SA 3.0

Isn’t Discourse cool? It even supports wiki posts. If I were starting TidBITS today, I think I’d do it all in Discourse.