Alternative syntax for links

[matklad]

TL;DR: I think that the following is a better (more uniform, easier to remember, with less gotchas) syntax for links:

• <https://example.com> (this we already allow)
• <example link https://example.com>
• <example link [1]>
• <example link []>

There are two problems with current markdown syntax: [link text](url):

• It is objectively hard to remember. Many people claim that it took them years to learn whether [] or () go first, and I find those claims very believable, as I am one of those people :P
• It is ambiguous, because URLs can and often do include () and [] (see URLs with parenthesis break parser djot.js#74)

There's one syntax that works great though: <url> for autolinks URLs. It works, because URLs can't include < and >, so it is unambiguous. Another thing that URLs can't include is a space, so the idea is to extend the angled syntax to all forms of the links.

• You can precede URL with a link text: <hello https://example.com>. Presence of is what distinguishes this syntax form just the link.
• For "refernce" URLs, you can include the reference instead of the URL: <hello [see here]>. This is better than markdown's [hello][see here], because its more obvious which part is the reference
• and then there can be a short-cut for self-reference <hello []>

I haven't thought through all the interactions with the parser, and there might be some terrible ambiguity here that would prevent this from working, but it feels like this should work, no?

If this does work, I am tempted to suggest that djot should support both <text url> as the canonical link syntax, as well as markdown syntax for compatibility.

[dalz]

As far as I can tell [] must be escaped in URLs too. Org uses [[url][label]].

However I disagree that links should be limited to URLs. It should be possible to link to files on the local file system, which can include spaces and <>. Spaces especially are common so they should not be dismissed as invalid.

[matklad]

Great point that links aren't always URLs. 🤔 Hm, I think we can allow "escaping" spacing using something like

<further info `./extra details.dj`>

but that moves the syntax closer to rST, which is my model for how not to do link syntax 🤣

[Omikhleia]

Perhaps I am missing something, but maybe [link text]<url> instead / in addition to the current [link text](url)?

• Keeps a similar easy-to-parse syntax
• Uses the more usual <...> for the link URL (mitigating the problem of never remembering the order)
• Interpretation of <url> is ~ [url]<url>

This does not help with links containing < and > but maybe the raw syntax suffers from this problem too. It's really an edge case, and indirect links might be sufficient in those cases.

N.B. One can have back-ticks (code-like content) in the link text, so using these is probably ambiguous.