New link syntax

John Gruber gruber at
Tue Mar 30 21:51:26 EST 2004

Aaron Swartz <me at> wrote on 03/30/04 at 7:04p:

> > this would only turn into a link if you also defined a link like this 
> > somewhere
> This seems pretty likely to me.

Can you provide an example where you think this might happen?

> I'd much a prefer a system ala the old atx proposal, but with a
> slightly more complicated link syntax, something like so:
> _John_ asked me about _the new elephant from Trolltech_. _I told him_
> I didn't know what he was talking about.
>       [John]:
>       [elephant]:
>       [told]:

Maybe it's just me, but I just don't get how the "keywords" would be
discerned here. Why, in the middle one, would the keyword be
"elephant" instead of "TrollTech"? What if you defined links for
both "elephant" and "trolltech"? Which link would apply to the
middle one above?

I do see how this idea could make links very easy to create while
writing, but I just don't think it's explicit enough. It just seems
too nebulous to me -- it's mostly simple, but I think the complete
set of rules to implement this would actually be fairly complex, in
terms of deciding what the keyword is in one of these links.

> Now `_` is probably not usable for this (since it's already used for 
> emphasis), but imagine it was replaced with something equally unlikely 
> to be typed accidentally.

Easier said than done. There aren't many punctuation characters
left. I don't want to use curly braces for this, because I want to
use them for class/id/tag-attribute assignments.

> What if there are multiple matches? The resolution algorithm is: 
> Process paragraphs backwards from link definition until start of 
> document. In each paragraph, try matching against each potential link 
> in order.

I think this would add *a lot* of complexity.

First, it'd be changing the rules for link definitions. The current
rule is that it doesn't matter where you define them. With this
proposal, the order of links would become important. And I'm not
even sure that reverse order would make the most sense. Proximity
might be more natural, but I certainly don't want to implement that.

Plus, also, it's more complex because it would eliminate the rule
that link text is *always* set in square brackets. That's the one
constant that ties together all the various ways that currently
exist to create links in Markdown.

With your example, above, I'd write it like this:

    [John][] asked me about [the new elephant from Trolltech][].
    [I told him][] I didn't know what he was talking about.
        [the new elephant from Trolltech]:
        [I told him]:

And this this new implicit syntax proposal, it could be this:

    [John] asked me about [the new elephant from Trolltech].
    [I told him] I didn't know what he was talking about.
        [the new elephant from Trolltech]:
        [I told him]:

I really like that.

Now, in terms of using this to satisfy your (Aaron's) desire to make
it as easy as possible to create links while writing, without
interrupting the flow, I say this. Just use the brackets, and
postpone defining the links. Then when you're done writing and are
ready to define your links, you could have a script that runs
through your text and finds every [link text] that doesn't already
have a corresponding link definition. Then spit out a bunch of empty
link definitions at the end of the doc:

    [the new elephant from Trolltech]: 

    [I told him]: 

I could probably slap together an AppleScript for BBEdit that does
this within a few minutes. And a Python or Perl script would be even
easier. (Well, the Perl one would be easy for me; the Python one
easy for you.)

And, also, if you have any sets of square bracketed text that you
didn't want to be a link [i.e. you just want to use real square
brackets, just like this], then you could simply delete the blank
link definition for that link.

This is just how I'd go about making this easier. The point is
simply that I think if really want to make your link creation more
convenient -- as in like insanely ridiculously convenient -- it's a
problem that you should look to solve in your editing environment,
not through Markdown's syntax.


More information about the Markdown-discuss mailing list