Babelmark 2 - FAQ

← Back to Babelmark 2

What is this for?

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.

What are some examples of interesting divergences between implementations?

Lists

Inline markup

Raw HTML

Other

Why does it matter whether implementations agree?

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!

What are some big questions that the markdown spec does not answer?

What was Babelmark 1?

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.

How does Babelmark 2 differ from Babelmark 1?

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.

How can I add my markdown implementation to Babelmark 2?

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.

Why is there a 1000 character limit on input?

A thousand characters should be sufficient to test syntax features. We impose the limit to reduce load on the servers.

What determines the order in which the implementations are listed?

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.