This is a tool for comparing the output of various implementations of John Gruber’s markdown syntax for plain text documents. The official markdown syntax documentation is silent or vague on many issues, and implementations have diverged in their interpretations of the syntax. Even when the interpretation of the syntax spec is not in question, implementations may have bugs. So it is useful to be able to see at a glance how implementations differ on various inputs. The hope is that this tool will promote discussion of how and whether certain vague aspects of the markdown spec should be clarified.
%0A){kind=link}
<ins> tag around paragraph<Markdown is everywhere these days. If the same document is interpreted differently in different places, that is a problem. For example, suppose you have a nice piece of documentation on a github wiki, and you want to turn it into DocBook using pandoc. Your sublists are indented two spaces, and this works fine on the wiki, but when you run the document through pandoc, these items are interpreted as parts of the main list. If you are lucky, you notice this before distributing the DocBook file!
How much indentation is needed for a sublist? The spec says that continuation paragraphs need to be indented four spaces, but is not fully explicit about sublists. It is natural to think that they, too, must be indented four spaces, but not all implementations require that. (Note that none of the implementations that allow a one-space indentation to start a sublist are entirely consistent about that.) This is hardly a “corner case,” and divergences between implementations on this issue often lead to surprises for users in real documents. See this comment by John Gruber.
Is a blank line needed before a block quote or header? Or can you have things like this:
*%5D(img.jpg)%0A){kind=link}
paragraph
> block quote
# header
paragraphMost implementations do not require the blank line. However, this can lead to unexpected results in hard-wrapped text, and also to ambiguities in parsing (note that some implementations put the header inside the blockquote, while others do not). John Gruber has also spoken in favor of requiring the blank lines.
Is blank space allowed between the [...] part and the (...) part of an inline link? That is, can you have a link like this:
[my link] (/url)There is some relevant discussion here.
What is the exact rule for determining when list items get wrapped in <p> tags? Can a list be partially loose and partially tight? What should we do with a list like this:
1. one
2. two
3. threeOr this?
1. one
- a
- b
2. twoThere are some relevant comments by John Gruber here.
When list markers change from bullets to numbers, should we have two lists or one?
Should two blockquotes with a blank line between them be treated as a single blockquote? Most implementations do this, but John Gruber has suggested that this be changed. (Waylan Limberg points out that the spec actually does seem to settle this question, in favor of a single blockquote.)
Can reference link definitions occur embedded in block quotes and list items? (The spec says they can be “anywhere in the document,” but most implementations require that they be at the outer level.)
The original Babelmark was written by Michel Fortin, author of PHP Markdown and PHP Markdown Extra. It is still running, but with very old versions of the markdown implementations.
Instead of asking the Babelmark maintainer to install all the converters on his server, and keep them up to date, we use a decentralized model. Each implementer provides a small “dingus server” that accepts textual input and returns HTML. Babelmark 2 queries these dingus servers asynchronously and combines their outputs into a page of results. This system puts the burden on implementers to keep their servers up to date.
Write a server app or CGI script that accepts accepts GET queries, takes the text out of the text parameter, and returns a javascript object with the following fields: name (the name of the markdown processor), version (the version being run), and html (the result of converting the text to HTML).
Example:
$ curl 'http://johnmacfarlane.net/cgi-bin/pandoc-dingus?text=hi'
{"name":"Pandoc","html":"<p>hi</p>","version":"1.9.4.2"}The script can, if desired, return an error if the input text exceeds 1000 characters.
Send the URL of your server or script to the Babelmark 2 maintainer, John MacFarlane.
A thousand characters should be sufficient to test syntax features. We impose the limit to reduce load on the servers.
The calls to the individual dingus servers are made asynchronously, and the results added in the order they come in. However, one should not infer that the implementations that appear at the top are the fastest. The performance differences in converting small bits of markdown are swamped by other factors, such as server latency and script startup time. For example, RedCarpet has the fastest parser of all the implementations, but often appears last because of the slow startup time of ruby scripts. And PHP Markdown is faster than Markdown.pl, but its dingus server is much farther away.