Do you like Markdown?  Do you wish you could use it when reporting bugs in JIRA?

Well good news everybody.  There is now an open source plugin for JIRA that gives you first class Markdown support.

Its based on the excellent PageDown library that forms the basis of StackOverflow’s markdown support.  One of the things I really loved about the PageDown code was that you could get a live client side preview of the rendered text as you typed.

There are two components that are provided by this plugin.  Firstly it has a full JIRA field renderer and hence you can set your description field, say, to be rendered via Markdown.

There is also a Wiki markup macro that allows Markdown to be used inside an existing wiki rendered field.  Now this twists my mind a little bit, Markdown inside Wiki markup, so I will explain it a bit more.

You can keep your existing Wiki rendered fields and still use Markdown by enclosing the Markdown text in a special {markdown} macro.  For example the following is mixed Wiki and Markdown text that produce very similar things :


1
h3. Wiki Header This is *bolded* Atlassian wiki markup text with a h3 header {markdown} ### Markdown Header And this is **bolded** Markdown text with a h3 header {markdown}

Notice the {markdown} macro statements. They denote that every thing you inside them is in fact not Wiki markup but Markdown. This will allow you to use Markdown on an existing instance more easily.

But if you are really dedicated to Markdown then you can set a field’s “renderer” in the field configuration as Markdown.

This will give you the excellent Pagedown editor support and live preview. Using the field renderer is definitely going to give you the best Markdown experience.

Here is a screenshot of the two types in action :

One of the more interesting features of the code is that it uses the same client and server side Markdown generation. I used the javax.script.ScriptEngine support on the server to render the markdown. So what you see in live preview is going to be what you get once you save the field. Cool eh?

This code was the result of the last Atlassian ShipIt Day. The code has been open sourced and is available on Bitbucket. While there is no official support from Atlassian I will try in a best efforts fashion to keep it up to date. If you want to fix something or improve it then fork the Mercurial repo and submit your changes.

The plugin can be found on plugins.atlassian.com under then name Atlassian JIRA Markdown plugin.