How to remember Markdown's link 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

It's [text](url) because it looks like a function call

Anti-mnemonic: (text)[url] would look like you are using the key url to access a value from an array or from the text string. That wouldn't make as much sense, would it?

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

[text](url "title")
[text](url 'title')
[text](url (title))

Result (×3):
<a href="url" title="title">text</a>

For completeness, let's see other ways of specifying links in Markdown.

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

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

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. Like so:

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

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

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

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

But wait! There's more.

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][].

[foo]: https://example.com/foo
[BAR]: https://example.com/bar
[baz]: https://example.com/baz

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

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

[foo]: https://example.com/foo
[BAR]: https://example.com/bar
[baz]: https://example.com/baz

Btw, images

I have previously struggled to remember Markdown's image syntax. While writing this blog post, I realized that the syntax is the same as the link syntax, except that there's a bang (!) at the beginning:

![alt text](url)
![foo][bar]
![ham][]
![spam]

Image with an empty alt text: ![](url)

[bar]: https://example.com/bar.jpg
[ham]: https://example.com/ham.jpg
[spam]: https://example.com/spam.jpg

Further resources

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