Design proposal for #153 (embedded link syntax)

["Larry Golding \(Comcast\)" <larrygolding@comcast.net>]

I read the GitHub Flavored Markdown spec’s section on links (§6.6). Here’s what I propose:

 

In a rich message, a viewer treats any link whose link destination is a non-negative integer as an embedded link. The full GFM link syntax is supported: inline links, reference links of all types, link titles, inlines of all kinds within the link text – you name it. Since a viewer needs a full-powered GFM processor to render rich messages, there’s no reason to limit the link syntax.

 

In a plain text message, to ease the burden on viewers the permitted syntax is a strict subset of the Markdown syntax. Only inline links are supported. Link titles are forbidden. Square brackets in link text must be escaped. Literal backslashes must be escaped. The link destination is a non-negative integer. Anything that does not meet this strict syntax is rendered as plain text.

 

NOTE: This is contrary to the existing spec, which makes no distinction between embedded links in rich messages and plain text message.

 

Examples of embedded links in rich messages:

 

1. Tainted data entered the system [[_here_]](  0 "source"  ).
   
   An inline link whose link text includes a balanced pair of unescaped square brackets and an inline italic element, and whose link destination includes the optional whitespace inside the parentheses, and a link title.
   
   The message will render as:
   
       Tainted data entered the system [here].
   
   A viewer can render the link title anywhere it wants to (for example, as hover text when the user mouses over the link text).
   
   
2. Tainted data entered the system [here][link].
   
   [link]: 0
   
   A reference link. The target is defined on a separate line. The message will render as:
   
       Tainted data entered the system here.

 

Examples of embedded links in plain text messages:

 

1. Tainted data entered the system [\[_here_\]\\](0).
   
   The link text includes escaped brackets and an escaped backslash. The link text includes what looks like an italic inline, but of course it renders literally:
   
       Tainted data entered the system [_here_]/.
   
   
2. Tainted data [wow!] entered the system [[here]](0).
   
   There are no valid links. The first pair of square brackets are not followed by a left paren. The contents of the second, outer square brackets don’t match the permitted link text syntax. The third, inner square brackets are not followed by a left paren. This message renders literally:
   
       Tainted data [wow!] entered the system [[here]](0).
   
   NOTE: contrary to the existing spec, this is a legal plain text message. The existing spec requires all square brackets to be escaped (in both plain text and rich messages).

 

Larry