Martin Fenner and Stian Haklev organized a one day Markdown for Science workshop at the Public Library of Science HQ in San Francisco on June 8th, 2013.

If you attended, please list yourself on [[people-attending]] with a bit about yourself, and your ideas/wishes for the workshop.

Please add to these two pages: [[Tools and projects]] (later we can clean this up and put some of it into [[Tools to support your markdown authoring]]) [[Scenarios, barriers to adoption, needs]]

Some of the potential outcomes of the workshop include:

  • [[Todo list from workshop]]
  • [[Signs that MD is successing]]
  • [[Barriers]]
  • [[What is Markdown]]
  • Notes from discussion about the suitability of Markdown for scientific authoring (different stages, disciplines, etc)
  • Comprehensive list of tools/initiatives
  • Notes from discussion about collaboration/synergy between tools
  • List of interesting examples/showcase (GH repositories etc)
  • List of "barriers", "obstacles" etc
  • Notes from discussion about way forward, applying for grants, etc

Please add your ideas below.

CSS Styles

@swcarpentry

@_inundata If you can make it easy (really easy) to add CSS styles to pre blocks in Markdown, you'll be my new best friend...

Use case is adding <span class="highlight"> or <span class="comment"> inside an indented block that triggers <pre>.

Mix Markdown with LaTeX

Paul Groth

One thing to say is that I like how authorea.com lets you mix and match markdown with latex. So a couple things to think about: * how do I transition from markdown to latex (do I want to?)

Mix and match. Write the easy stuff in Markdown and if you are used to writing tables in Latex then stick to Latex for tables. In the near future, on Authorea we could offer an automatic conversion between the two, so you could select a paragraph, click convert to markdown, and you are good to go. For the time being, you can write in Markdown and then convert the entire document to Latex, for example. Although this is still rough around the edges, it is a step in the right direction. Overall, we prefer to impose limitations on what users can do so that we can guarantee them a minimum level of conversion between MD and LaTex. In other words, if we start supporting crazy complicated tables with mini pages, multicolumn, and other (unnecessary imho) Latex environments, we will make it hard/impossible for that content to be displayed in HTML5 and then converted to MD. But, if users write more regular, simpler tables, conversion between the two (or 2+) formats can be guaranteed. So, imposing limitations is the key, we think. FYI we use Pandoc to convert between formats. - Response from Alberto and Nate, creators of Authorea.

  • how do you deal with style files?

    When exporting to pdf we convert markdown to latex and the style file is handled naturally. Online we have our own look. If we wanted to offer authorea as a platform for journals (create->publish under a different name, ie not authorea but journal x), we could also allow custom css files. - Response from Alberto and Nate.

Standard additional markup

Philip Lord

It would be good to have some discussion on additional markup that might be needed for science. For example, I use [cite]doi://10.1000/1.1.1.1[/cite] or [author]Phillip Lord[/author] to define the author, within my wordpress plugins.

It would be nice to have some commonality both in the syntax (for example, "shortcodes" as I have used here) and the vocabulary. Ideally, something that will work in Markdown, but also non-markdown text syntaxes or even in word.

In Authorea we support citations, references, labels, and other Latex-native features in Markdown. We are still not sure which way scientists want to go. At the moment, if you are writing a Markdown doc you still cite using \cite{xxx}. Maybe sticking with the standard latex format is good enough for most of our users, maybe there would be a more concise syntax. We are not sure. - Response from Alberto and Nate

Relying on LaTeX markup for features we see as essential for Scholarly Markdown is a non-starter if the aim is to move beyond just the PDF/dead wood publishing model. We'd certainly want some form of extended MD markup and a processor to write to HTML for example as well as to LaTeX, but also to one or more of the HTML-based slide stacks. - Gavin Simpson

The sweet spot for markdown in scholarly communication

Karthik Ram

Markdown's greatest appeal is its simplicity. Adding features to support more complex use cases could be very counterproductive and we would worse off than just using LaTeX. So what are some of the key features we would need to implement to make markdown a standard tool for scholarly communication? Might be worth spending some time generating such a list and possibly build some prototypes time permitting.

31 flavors is great for ice cream but not markdown

Karthik Ram

There are many flavors of markdown at this time. Creating yet another one does not really help. Could we look through existing implementations and identify key features that facilitate scholarly use? For e.g. GitHub has its own non-standard flavor but some of their features are perfect for use in peer-review. Could we combine useful features into a scholarly markdown flavor (ok 32 is not so bad because this one is going to be the best).

There is no flavor of markdown out there now that is fully sufficient for scholarly publication. At Authorea we use Github flavored MD with some ad-hoc extensions for references, labels etc. These are all plain Latex extensions (i.e., we allow some Latex in MD). By all means, extension of MD will be necessary for science articles. And some of the extensions for science will not be useful for other uses of MD, most likely. - Response from Alberto and Nate.

Challenges

Martin Fenner

What will it take for a critical mass of researchers to use markdown for authoring? I think the biggest challenge is usability - most researchers aren't interested in learning a markup language. We therefore need nice WYSIWYG editors along the lines of Google Docs, that it is markdown (and git) underneath should matter only for the technical implementation and a small group of geeks. The other challenge is features, but here users may be much more forgiving.

One possible outcome of the workshop for me is that we are better off using the existing tools from LaTeX to online editors working directly with HTML5, and that markdown doesn't really fill a need.

Workgroup: Editing Tools

Our notes are [[here|Editing-Tools]].

The point about hiding MD behind a GUI diminishing the point of using MD in the first place is well made and we'd do well to remember this as work progresses. I like the interface of a Linux app, Gummi, that has a split screen interface with an editor window for LaTeX on the left and a preview of the rendered PDF on the right. As you update the code in the left pane, the document is recompiled and shown on the right. This strikes the right balance for me in having readable code with instant gratification. I suspect Gummi could be adapted right now to build MD files by use of a custom build process (via rubber or similar) - we'd only be missing the highlighting for MD syntax in the editor. - Gavin Simpson (@ucfagls)

The event is supported by a 1K Force11 Challenge prize.

Please contact the organizers @houshuang and @mfenner if you want to give a presentation or demo.