Markdown

Why does Markdown even exist? What’s wrong with reStructuredText?

posted by Bob Ippolito at March 19, 2004 06:54 PM #

Is there a Python version of Markdown in existence?

posted by Xian at March 19, 2004 09:09 PM #

And what about Textile?

posted by jazer at March 19, 2004 10:03 PM #

I dig it.

In response to the question about reStructuredText, I would just point out the contrast between these two documents:

• reStructuredText primer in reStructuredText format
• reStructuredText primer in Markdown format (via html2text)

The Markdown format is a lot easier to read, and probably a lot easier to write. The HTML output from passing that html2text text back through Markdown is a little different than the original HTML document, but I don’t think it would be difficult to get it back to nearly the same result. The point is the difference between producing a piece of writing and creating an HTML document. Having to do the first by also doing the second is tedious.

I also dig that Markdown.pl works as a blosxom plugin out of the box. (Btw, if you use the writeback plugin, I have a 1 line diff for adding Markdown support to user writebacks here.)

posted by Greg at March 20, 2004 01:15 AM #

Are you guys aware of YAML?

I took the “learn YAML in 5 minutes” experiment, and it took me around 4.5 minutes, if I recall correctly.

I liked it!

Looking forward to using more markdown/yaml ‘ish stuff…

posted by Zooko at March 20, 2004 05:48 AM #

Here’s my asciinated web log . (Here’s the original.)

I wonder what it will look like when I run markdown to htmlify it.

Would you rather receive the ASCII version in e-mail than read my web page? I guess I should learn how to do RSS feeds…

posted by at March 20, 2004 05:54 AM #

You can write reStructuredText just about as lazily as you can write Markdown. The comparison you make is a bad example, the source reST document has a lot of metadata, which means more markup, but it makes the output more flexible (i.e. a table of contents that makes sense could be automatically generated).

Also, a lot of the markup is taken out by the markdown converter because the links are numbered instead of named.. which isn’t something a human would probably do for a document with 42 links!

If you take the metadata out of the reST document, or put it into the Markdown document (i.e. name the links, if that’s possible), the documents become largely equivalent in readability and writability. However, the reST markup has been around much longer, has much more software that uses it, stable and complete APIs are available for Python and Perl (probably others), has outputs other than html, and it’s designed for extensibility. For example, you can add arbitrary new types of blocks with “plugins”… you know, for those times where you’re writing something other than a weblog.

posted by Bob Ippolito at March 20, 2004 07:07 AM #

If you take the metadata out of the reST document, or put it into the Markdown document (i.e. name the links, if that’s possible), the documents become largely equivalent in readability and writability.

Perhaps, (and perhaps the example is unfair) but the point is that Markdown is made for the purpose of writing for publication on the web without knowing any syntax necessarily. Its un-syntax is the point. It makes it easy for an email-savvy, weblog-savvy, HTML-unsavvy person to get their words on the page. I think that Markdown is better suited for that (its purpose) than reST is. The comparison between the documents was to point out the syntax differences: nobody writes an email like reST, whereas the Markdown source could have been sent as an email just fine. If written by hand the links would certainly have been named rather than numbered.

The Dive into Markdown article is worth reading.

(Btw, reST seems great for other purposes, especially writing documentation. Is there an extension for converting to Docbook? If so I may have to learn more about it. It may even have been a good weblog/discussion board post writing formatter, but I’ve never seen it used as such.)

posted by Gregory at March 20, 2004 10:57 AM #

I’m actually working on a similar markup tool, spurred by my frustration with the existing ‘simple’ tools - reStructuredText, Textile, etc. They’re good tools, but the markup leans towards complex, considering their stated goals. That’s my opinion of course, but I dream of a simpler tool.

Markdown looks to have some interesting possibilities, I’m interested to see where it goes. I’m always amazed at how many people are attacking similar problems at the same time :)

My 2 bits is that plain markup tools need to do more magic. Tools in general do, but markup tools should make specific markup tasks easier. I have dreams of generating graphs from ascii art or from included csv data, auto-formatting recipes, colourizing source code (automatically of course) and the like.

posted by mx at March 20, 2004 11:54 AM #

My god, this is too cool… thank you.

posted by joe at March 20, 2004 01:27 PM #

It seems to me that a user of a weblog software package will know HTML but the chances are much smaller a user will know a recently-invented meta-language.

Plus, HTML is a widely accepted standard that is useful in other contexts, whereas a new metalanguage only has one application (so far, granted).

If the user has a choice of learning something that is applicable one place and something that is applicable many places, wouldn’t they opt for learning something applicable in many places?

HTML’s b, i, img, a href, h2, h3, p, br tags are all one really needs, and it doesn’t seem that hard to wrap things in < and >…

posted by Dominik Rabiej at March 20, 2004 02:28 PM #

I find it strange not to find the word Wiki anywhere on the Markdown Site. Sure there have been ascii2html formatters before but not as divers or widely used. This created a lot of discussion which might have saved you a lot of figuring.

Example? Starting every line with “either 4 spaces or one tab” only works with good editors, so most Wikis abolished it long ago.

posted by Tobias Weber at March 20, 2004 02:35 PM #

I fail to see the huge benefits over ReST. Sure, I’m the author of the ReST Primer, but really, looking at them, I can’t see it. To be honest, some of the Markdown stuff looks… well, how is:

# [Structure][11]

better than

Structure
---------

as a heading? I dunno.

Anyway, why not just plug in Epoz and be done away with all this cryptic editing altogether :)

posted by Richard at March 20, 2004 04:04 PM #

yes, reStructuredText can do docbook.

I have written structured emails in reStructuredText format, and sent them to people who have no knowledge of HTML syntax, reST, Python, etc. and they had no problem understanding it.

For the simple stuff (bold, italics, sections, etc.) reST basically is what you would write in an email (assuming monospace font).

posted by Bob Ippolito at March 20, 2004 04:19 PM #

John, Aaron: I. Love. You. Guys! Thank you so much for Markdown.

I’ve never understood why people liked the cryptic, feature-bloated syntax of most Wiki packages (and Textile too) better than just writing plain HTML. Markdown seems so natural in comparison, and I particularily love the way you allow a mixture of ordinary HTML and Markdown syntax within the same file, and the intelligent handling of code examples and character escaping. Those are Markdown’s killer features IMO.

I think most Wikis (including the Wikipedia) could benefit greatly if they adopted Markdown as their default syntax option.

posted by Már at March 20, 2004 08:19 PM #

Just a teeny little nitpick: “available under the GNU GPL” is a little redundant. The only GPL is the GNU GPL. It’s like saying “the Manhattan in New York”, or “Boeing’s 747”.

posted by at March 21, 2004 11:08 PM #

Actually, there’s the Affero GPL, the nethack GPL, and probably others. Even if there were no others, it’s not unlikely that someone may come up with a “General Public License” in the future, so it’s good to distinguish.

posted by Aaron Swartz at March 22, 2004 12:02 AM #

Bob Ippolito wrote:

Why does Markdown even exist? What’s wrong with reStructuredText?

Why so touchy?

Is there a Perl implementation of reST, or a Movable Type single-file plug-in wrapper? As far as I’m aware, no. So, even without any arguments about reST’s syntax, I just don’t see how one could argue that I could have just used reST.

And if I was going to write my own code, there was no way I was going to write code to re-implement reST’s rather large feature set. I’m much too lazy.

I’ll happily admit that I was inspired by a few bits and pieces of reST’s syntax, but to be honest, when I was at the point of deciding whether I should write something new or just use an existing formatting syntax, reST wasn’t even in the running. To me, the best parts of reST are the parts it borrowed from Setext.

posted by John Gruber at March 22, 2004 12:12 AM #

My major complaint about reST is that it requires documents be filled with all sorts of magic _s and :s and ..s and other nonsense — Markdown seems much cleaner to me. (I also don’t like reST’s section syntax.) When I come across a reST document (and I’ve come across a number in Python work), it immediate screams “something is going on here”, whereas Markdown is readable, and often undistinguishable from a normal email.

I’m not sure that reST’s age or increased set of software buys it anything — a format only needs one parser to be useful. I’ve never had much need for formats other than HTML and text. Markdown has already been extended (e.g. through SmartyPants) via its low-tech extension interface.

posted by Aaron Swartz at March 22, 2004 12:23 AM #

Is there a Python version of Markdown in existence?

No, but it’s easy to call the Perl script from Python:

import os
def markdown(text):
    i, o = os.popen2("perl Markdown.pl") # let the Perl code take it
    i.write(text); i.close()
    return o.read()

posted by Aaron Swartz at March 22, 2004 12:23 AM #

By the way, Nick Moffitt implemented a similar idea called tron in awk, for use in formatting some documentation pages for the LNX-BBC project. I’ve never used it, but it seemed to be pretty similar in concept to your project.

posted by Seth Schoen at March 22, 2004 01:08 AM #

Is anyone working on a PHP implementation of Markdown? I’d like to try Markdown on my personal weblog/wiki system, but the external process solution suggested above is a bit too heavy for my needs.

I can offer help in testing and fixing bugs if someone has already started. Otherwise I’ll probably write the PHP version myself.

PS. Any ideas on using Markdown as wiki markup? Would it be better to support wiki-links (CamelCase, brackets, or other some mechanism) as a pre- or post-processing step, or to integrate wiki support directly in Markdown?

posted by Jukka Zitting at March 22, 2004 04:52 AM #

I’m working on a Markdown wiki. My current plan is to use [[double brackets]] as the Wiki syntax, ala MediaWiki (Wikipedia). I’ll probably do this in postprocessing, avoiding <pre> and <code> tags.

I’m not too worried about calling out to a separate process — it’s pretty cheap most of the time. If it actually does become a bottleneck, you can pretty easily switch to a server-client model. Having Markdown in your favorite language, while nice, is probably not the best use of time.

posted by Aaron Swartz at March 22, 2004 10:53 AM #

Is anyone working on a PHP implementation of Markdown?

I am not.

But I’ve received email from several people who say they’d like to port it. If anyone is successful, I’d be delighted, and I’ll certainly link to the port(s) from Daring Fireball.

My best guess, however, is that a PHP or Python port would require a bit more engineering than a simple Perl-to-foo translation. I suspect certain of the Perl idioms (especially advanced regex substitutions) I use in Markdown.pl can’t be directly translated to either PHP or Python. In other words, I think it’d need to be rewritten in another language, not merely translated.

posted by John Gruber at March 22, 2004 01:00 PM #

My current plan is to use [[double brackets]] as the Wiki syntax.

Wouldn’t it make sense to just use the [single bracket][SingleBracket] syntax that Markdown already uses and just process wiki links after Markdown. Since all non-existing Markdown link brackets are still in the document after processing. That would keep it from adding a whole new concept.

You sould even use the [empty single bracket][] syntax for self-referencing wiki links.

Also, do you foresee any problems with Markdown’s indentation in webforms? On OSX with text extras indention is handled nicely, but on many browsers/systems it is not.

posted by Xian at March 22, 2004 04:59 PM #

Comparing rest to markdown primer. In the first four lines the following were different.

No footnote on Contents The Author and Version don’t appear to be semantic (i.e. it’s just text.. whatever happened to the semantic web) The ReST document includes auto replacements

If you only want to use the basics of ReST do so but compare like for like. As for headers, the # bits look more like comments.

In general I think it’s better to spend time extended, documenting or contributing to good existing projects rather than writing yet another version. In this case, an extension module for ReST or some better documentation could have acheived everything here, made ReST better and avoided wasted effort on two different projects

although my main url is pollenation.net my blog is here

posted by Tim Parkin at March 28, 2004 10:28 AM #