By Deane Barker on September 2, 2004

Daring Fireball: Markdown Syntax Documentation: I’ve been playing around with some of the plugins in the MT3 Plugin Pack. Markdown is a plaintext to HTML convertor, much like Textile. However, there’s a philosphy behind it:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. […]

He’s really on to something here, because even unconverted, raw Markdown is really, really readable, due mainly to his removing URLs from the flow of the page. This seems like a small thing, but, in practice, it makes things SO much easier.

Here, read this. This is some markdown text for one of the pages on his site. You can read it really well, can’t you? And this is raw — the post-Markdown version is here.

I really like the practice of the “reference” style URLs. For instance, this markdown…

[Gadgetopia][gdtc] is a good site.

…will link the words “Gadgetopia” to a URL specified anywhere else on the page, like this:


So you could set all your links up like footnotes at the end of the text, instead of jumbled up in the word flow. Very nicely done. I could actually see unleashing Markdown on users, whereas Textile was a geek-only affair.

What Links Here


  1. [Note: After this comment was posted, I edited the entry and removed incorrect information. — Deane]

    “Or you can omit the second bracketed phrase completely”

    Actually, you can’t omit the second bracket completely, However, you can leave it empty, like this:

    [Gadgetopia][] is a good site.
    ..and later on that page...

    Much discussion went on about this on the Markdown mailing-list earlier this summer, and it was decided (by John) that requiring the pair of empty bracket, was a tiny sacrifice in readability really worth accepting, because it removed a lot of ambiguity from the syntax.

  2. It doesn’t work too well. When I entered

    Happy Birthday Deane

    I got the H3 tag when I looked at the preview, but it still had the hash marks in it on the front page.

Comments are closed. If you have something you really want to say, tweet @gadgetopia.