One important outcome of the recent Markdown for Science workshop was an overall agreement that all the different implementations (or flavors) of markdown that currently exist are a big problem for the adoption of Scholarly Markdown and that we need:
A reference implementation with documentation and tests
As described by Karthik Ram (31 flavors is great for ice cream but not markdown), me and others, there is really a large number of markdown implementations to choose from, including
These different flavors all serve their needs, but for Markdown to take off in the relatively small scholarly community it would be very helpful to come up with a reference implementation. But how do we get to that point?
I think as a starting point, and until we come up with something better, #5 makes the most sense. The number of markdown users among scholars is still small, but my guess would be that Pandoc is currently the most popular Markdown flavor among scholars. This blog uses Pandoc and the static site generator Jekyll, and is hosted on Github Pages - for the source code use the link in the footer. Please tell me in the comments what you are using (Markdown flavor and tools), and whether I am correct with my wild guess regarding Pandoc. And make sure your preferred tool is listed in the Tools to support your markdown authoring wiki page.
A reference Markdown document is also very helpful to move forward, as we can see what outputs in HTML, PDF (or other formats) our specific Markdown tools produce, and how they differ. This reference document should include citations, tables, figures, and other features typical for scholarly content. Ideally this is a paper written in Markdown and accepted for publication - proving the concept -, or it can be a published paper transformed into markdown, e.g. a paper by eLife. Feel free to suggest a paper in the comments.
The idea of tests that came up in the Markdown workshop is also great. Ideally we have a set of tests that we (or someone else, e.g. a publisher) can run to make sure that the markdown in the document conforms with the reference implementation. This could also include basic checks for required metadata (title, author, publication date, etc.), and could optionally validate the citations as well.
What is Scholarly Markdown?
One of the important discussions taking place at the Markdown for Science workshop last weekend was about the definition of Scholarly Markdown. We came up with this:Markdown that supports the requirements of scientific textsMarkdown as format that glues...
Announcing Markdown for Science Workshop on June 8th
On Saturday June 8th – exactly a month from today – the PLOS San Francisco offices will host a workshop/hackathon about using markdown for science. A lot of people are experimenting with markdown for authoring scientific articles – see blog posts here,...
Introducing the Scholarly Markdown Bundle
Using Markdown to author scholarly documents is an attractive alternative to the standard authoring tools Microsoft Word and LaTeX. The feeling shared by many is that Scholarly Markdown is 80% there, and that more effort is needed for the remaining 20%...