I had a great idea for a Confluence add-on, but timing really is everything...

Like many others I've been using GitHub, Bitbucket and Stash for some time now and enjoyed the simple Markdown syntax for creating README.md files. It takes a little getting used to when exposure to Confluence's old wiki markup means that you are conditioned to write the wrong thing, but overall I like it.

So one day in June when I'd just pasted some text from a Stash README directly into Confluence it stuck me that Confluence should have a markdown macro. Having had this thought, it seemed obvious that some one else must have thought the same and acted upon it already. A quick Google search proved me wrong.

There was no Markdown macro for Confluence.

Surely not? Such a macro would perhaps appease the wiki markup faithful to some extent.

It was a Friday night and I was at home with my kids asleep upstairs. As this was clearly such an excellent idea, I set about righting this wrong immediately. So Markdown for Confluence was written. Amazingly, the macro was up and running within half an hour as the excellent pegdown library meant that I had to write almost no code whatsoever. I probably spent more time adding a logo and the macro placeholder image.

The crux of the add-on was just this method:


@Override

public String execute(Map<String, String> parameters,

                      String body,

                      ConversionContext conversionContext)

        throws MacroExecutionException

{

    PegDownProcessor processor = new PegDownProcessor();

    return "<div class="markdown-macro">" + processor.markdownToHtml(markdown) + "</div>";

}

MVP completed, I moved on to those new-fangled Blueprints I'd heard so much about. Yay, the add-on now had the Blueprint feature, which is kinda neat. All pages created with the markdown Blueprint were labeled as such and conveniently listed in the left hand menu of every space.

Timing

So the code was pushed to Bitbucket and built ready for release. But wait, Atlassian released their own markdown macro the very day I wrote mine. Timing eh?

Further, Bob Swift released yet another Markdown add-on within about a week or so.

Just like mine, both of the other add-ons used the pegdown library and also version of Dustin Curtis's Markdown Mark.

Release?

I didn't release the add-on to Atlassian Marketplace. Arguably 2 plugins that seemingly do the same thing is plenty to choose from. Instead I've made the source and the installable jar files available on my Bitbucket page - you can get it from there gratis and use it however you like.

A playground

So why did I continue to work on this add-on? Well the short answer is that this add-on is a small playground for me to try stuff. It enables me to try out new features somewhere that's safe and importantly, produce some simple code examples.

After the initial release I remembered that Markdown allows you to pass unsanitised HTML directly onto a page. Sounds like a little bit of a security flaw if you ask me, so I added a configuration screen. The add-on escapes the HTML by default but you can change this if you really feel that XSS isn't something that will ever happen to you.

Code Examples

As I've previously noted, this add-on features one of the simplest code examples for writing a macro that I've seen. That's handy.

Blueprints are newish. This add-on has them.

I was also interested in server side rendering of soy. So, the configuration screen is a servlet that renders using soy templates instead of the normal Confluence practice of using actions and velocity. Having written this in soy, it's now a reasonable code sample that I can go back to when I need to do something similar. In fact, the more soy that I write, the more I'm enjoying it. Writing in the same templating language for both server and client side code is quite appealing.

Try out Markdown for Confluence

If you're interested in using the add-on...

Download it now!

The source code is available here under Apache 2.0 license. Fork it, play with it. Send me your improvements. If it was useful, let me know.