Skip to content

Mnemonic for Markdown's link syntax (and image syntax)

Published on in Markdown and Mnemonics

Last updated on

Was it [text](url) or (text)[url]? Use this one weird trick to remember – Markdown consultants HATE it! Spoiler: it's the former since it looks like a function call.

Table of contents

Skip table of contents

The first part looks like an array of words: [link text].

The second part looks like it's used to call a function with one parameter: (url).

Put together:

[I'm an array of words](/and-im-a-parameter-to-a-function-call)

[Link text with **bold words**](https://example.com/)

Optional second parameter

Thinking of functions, you can also provide a title as the second parameter. These are all valid and identical (according to the CommonMark Spec):

[Link text](/some-url "And a title")
[Link text](/some-url 'And a title')
[Link text](/some-url (And a title))

Output (×3):

<a href="/some-url" title="And a title">Link text</a>

The title attribute is not very accessible, so you shouldn't rely on it too much.

Anti-mnemonic

(link text)[url] would look like you are using the url key to access a value from... hmm, from the expression (link text), which isn't even a valid expression? That wouldn't make as much sense.

For completeness, let's see other ways of specifying links in Markdown. Reference links are also related to Markdown's image syntax.

These are simple: wrap an absolute URI or an email address in angle brackets.

Example:

<https://example.com/foo/bar>
<mail@example.com>

Output:

<a href="https://example.com/foo/bar">https://example.com/foo/bar</a>
<a href="mailto:mail@example.com">mail@example.com</a>

A reference link consists of link text and a link label.

The link label should have a corresponding "link reference definition" somewhere in the document, for example at the end of a section or at the end of the whole document. Link labels are case-insensitive.

Example:

Check out [foo][1], [bar][2] and [baz][3].

[1]: https://example.com/foo
[2]: https://example.com/bar
[3]: https://example.com/baz

Do you know what's [my favorite search engine][duck]?
I like it more than [Microsoft's search engine][bing].

[duck]: https://duck.com/
[bing]: https://bing.com/

Output:

Check out
<a href="https://example.com/foo">foo</a>,
<a href="https://example.com/bar">bar</a> and
<a href="https://example.com/baz">baz</a>.

Do you know what's <a href="https://duck.com/">my favorite search engine</a>?
I like it more than <a href="https://bing.com/">Microsoft's search engine</a>.

Collapsed reference links

If the link text and label are the same (labels are case-insensitive), you can use "collapsed reference links" and drop the label:

Check out [foo][], [Bar][] and [BAZ & qux][].

[foo]: https://example.com/foo
[bar]: https://example.com/bar
[baz & qux]: https://example.com/baz

Shortcut reference links

"Shortcut reference links" take a step further by allowing you to drop the empty brackets as well:

Check out [foo], [Bar] and [BAZ & qux].

[foo]: https://example.com/foo
[bar]: https://example.com/bar
[baz & qux]: https://example.com/baz

The image syntax is the same as the link syntax, except that there's a bang (!) at the beginning, and the link text is the image's alt text:

![A nice pic](/image-url)
![A nice pic][a nice pic]
![A nice pic][]
![A nice pic]

[a nice pic]: /image-url

Output (×4):

<img src="/image-url" alt="A nice pic" />

Omitting the alt text produces alt="":

![](/image-url)
![][a nice pic]

[a nice pic]: /image-url

Output (×2):

<img src="/image-url" alt="" />

Nothing special; just the same link syntax where the link text is an image:

[![A nice pic](/image-url)](/link-url)
[![A nice pic][a nice pic]](/link-url)
[![A nice pic][]](/link-url)
[![A nice pic]](/link-url)

[![A nice pic](/image-url)][some page]
[![A nice pic][a nice pic]][some page]
[![A nice pic][]][some page]
[![A nice pic]][some page]

[a nice pic]: /image-url
[some page]: /link-url

Huh, quite busy syntax.

Output (×8):

<a href="/link-url">
  <img src="/image-url" alt="A nice pic" />
</a>

Further resources

The CommonMark Spec has more examples and edge cases covered. Check out these sections of the spec: