Markdown not escaping link id

John Gruber gruber at
Sun Oct 31 23:07:50 EST 2004

[I know this is a few weeks old; sorry I'm so behind. -JG]

Christopher Biagini <chris at> wrote on 10/13/04 at 3:54pm:

> In previous versions of Markdown, I'd always get caught up because I 
> tend to introduce blockquotes with a colon at the end of the preceding 
> line, and then indent them by a tab--triggering a code block. Now, 
> other elements of the document are being turned into code blocks.  Each 
> time it happens, I have to concern myself with Markdown syntax--which 
> kind of wrecks the beauty of it all.
> What's worse is that this syntax--colons, indenting, whatever--doesn't 
> look like anything in particular. It's natural for the writer (well, me 
> at least) to indent things like lists and quotations by one tab, simply 
> because it's convenient and it looks right. Same goes for link 
> definitions. I guess it depends on how often you write code examples, 
> but I find that the structure that Markdown's new syntax imposes on my 
> documents isn't worth the convenience of it making code blocks 
> automatically.

For a long stretch during Markdown's development, the syntax for
creating blockquotes was to indent them, rather than use email style
">" quoting. The idea was that indenting them was visually more like
what you see in a blockquote in a web browser. Aaron Swartz is the
only other person who used this version of Markdown.

Things got really tricky with this scheme, however, when it came to
things like lists-within-blockquotes, because of the way that
multiple paragraphs in a list need to be indented.

The `>` prefix style of blockquoting is also rather intuitive,
because of its longstanding use in email, and also makes it much
easier to parse and to read and write things like lists or code
blocks within blockquotes.

Once I changed blockquotes to use `>` prefixing, that freed up
indentation to be used for something else. Code blocks seemed like a
natural fit. The only other idea I had for code blocks was to
require them to be prefixed with `:`, like this:

: sub foo {
:     print "foo\n";
: }

But where this breaks down is if you use real tab characters to
indent lines of actual code, because then the `:` or `: ` prefix
would throw off the alignment of your tabs.

It just didn't seem to work as well as simply using indentation for
code blocks.

> Note that blockquotes don't have this problem--they're clearly defined 
> with the conventional `>>`. Indeed, even code *spans* don't have this 
> problem, because they too are so clearly defined. Why not require a 
> clear definition for code blocks as well?

I think it is unambiguous using indentation -- indenting with 4
spaces or 1 tab means you're in a code-block.

In Markdown 1.0, there is an exception for link definitions:


which can be indented by any amount of spaces/tabs and will still be
treated as link definitions.

I'm leaning strongly toward changing this in Markdown 1.0.1, such
that link definitions could only be indented by 0-3 spaces; at 4
spaces (or a tab), they'd be code blocks.

This change will break any existing Markdown source where people
have indented their link definitions. This includes some of my own
Markdown source. However, with this rule in place, the syntax rules
for treating indentation-for-code-blocks are completely consistent.

I hope to have a beta version of 1.0.1 available for testing very
soon. Feedback on this change will be much appreciated.


More information about the Markdown-discuss mailing list