The way to remember that is that the link is important.

For example, [[www.example.com]] makes sense.. it will render as www.example.com that hyperlinks to that link. But [[link description]] is useless by itself.

So.. put the more important thing first, the link:

    [[www.example.com]]

Now, if you also have a description text for that link, put that afterwards..

    [[www.example.com][link description]]

Hope that helps.

Often the link description is the most important thing, and may make sense without the link, so I'm not sure how well that would work.

To me putting the link first is extremely counter-intuitive, as if writing plain text I'd also be more likely to write out a description of what I'm referencing first, and then enclosing the link in parentheses.

Thankfully with Markdown that makes it easier to remember - the URL part is as it always was, and I just need to mark which part of the text makes up the description.

Clearly the link is more important than the link description. There is a really surprisingly good document [here] that explains why in detail :P

You never should use "here" for links. It's bad semantics for hyperlinks, and there could be tens of thousands of links with the title "here." Compare:

> [The W3C recommends not using "here" or "click here" for links.](https://www.w3.org/QA/Tips/noClickHere)

According to the original vision of hypermedia, the text should be able to stand on its own and the hyperlinks are added on top of it. This keeps the link text semantic by itself without relying on the hyperlink.

In html the link comes first <a href="link">Link Text</a>. So I would bet that most people are more comfortable with the link coming first.

I'd argue that if you are writing text, you'll put the description first and then look up the link. Because the description is often part of the sentence, and the link is not.

In fact you may write the entire thing first then look for whatever can or should be hyperlinked.

Most people wouldn't be able to explain to you what a HTML tag is, much less write one.

And the entire point of Markdown is to get something that is closer to how we write plain text.

I'm more comfortable with the text coming first, followed by the link. The rails `link_to` helper is:

> link_to "Text", "http://example.com"

And Markdown:

> [Text](http://example.com)

It's pretty easy to remember the order after a while.

Short of explicitly labeling each part (which would not be in spirit of 'lightweight markup'), it's hard to imagine any link/description markup that is completely foolproof. The advantage over markdown here is that you are really only likely to get one part of the links wrong: the order. In markdown, you might also get them out of order but you may get the brackets wrong too. Then, having realized something is wrong, fixing it way more complicated. With Org-Mode, you notice your link isn't working right so you swap the order and you're done.

To me, markdown and org-mode look completely equivalent. Surely there are small differences, which have to be learnt. Either way you have to remember some small details.

In org you don't need to remember. You just `C-c C-l` and it interactively asks for a link. You can type it or paste the link from your clipboard. _Then_ it asks you for an optional description.

The same command works if you want to edit a link under the cursor.

Also, most people have `C-c l` bound to a function that “captures” the link from wherever you are in Emacs (e.g. a newsfeed, a document, an email, a folder) so you can easily reference those places from within Org.

I think we should either compare these languages in a plain text editing context, or when used with editors with support for the syntax. Anything else seems like an unfair comparison to me.

Because editors with MD support tend to have shortcuts for inserting a link or image too, so this isn't really an argument in favour of either syntax.

I agree with you. My intention was to perhaps highlight one of the ways that using Emacs can help someone be productive using markup (but as you pointed this is probably true of other editors with strong support for the language) and maybe help someone discover an important feature of the editor that they have missed.

"Most people" :)

Fraction of people who have Emacs installed. Fraction of people who use Emacs for things other than programming. Fraction of those who use org-mode.

Well, "most people" in the context of my comment was exactly that small fraction. You really thought that I was talking about the entire world?

As an Emacs user I know most of humanity is far from ignumitation. (And also have bad sense of humor)

As mostly an org user, I still find that part of the markdown syntax to be more intuitive: parentheses are commonly used to clarify or expand on something, and links are often inserted with the same purpose, so a link goes into parentheses. E.g., "foo (you can find it there)".

I struggled with it, until I learned about "reference style" links in the original Markdown spec:

this is a link [1]

[1]: <link>

would display 1 and direct you to <link>. Then inline links are just reference links but you have the location in parenthesis after the link body, as an aside.

The reference style is my mnemonic to the order as well as where the parentheses are for non-reference links: since the reference definition uses []: then the reference uses [] too, and since the reference comes naturally after the text, then a non-ref link has the URL in not-[], hence (), and after the text too.

IOW I just think about "inlining" the reference, which would have otherwise used [] everywhere. Feels much more regular that way around.

The way I remember [] before () is that [] is "basic" and square and () is "refined" and curvy. Seems silly but it helps me.

"squared circle" = []()

https://en.wikipedia.org/wiki/Squaring_the_circle

i can't remember who i heard it from first, but "squaring the circle" is the phrase that (finally!) helped me remember the order after years of having to look it up every single time i needed it.

i still have to look up the format for images every time.

I remember “brackets come before parentheses” alphabetically ;)

These are both helpful mnemonic tricks. I always forget links' syntax.

More generally in this post I find Markdown has a pretty short learning curve, is highly readable and logical (EG. I like the number of `#` for level of headings). My biggest issue with Markdown is the different interpretations and how they're represented. Eg. Github vs. someplace else vs. Markdown-viewer apps. Org in comparison looks more concise, but less readable, IMO.

I always sort of read it to myself. I use parens within normal writing as an aside (for example, this one), so I put the part that you read within the brackets and the reference in the parens.

In plaintext you'd have a claim (and parens directing you to see the citation at citation.com).

In hypertext you'd have a [claim](and a link to citation.com).